Deploy pi cli web docker server

.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+output
+.git
+.cache
+*.log
+*.png

Dockerfile

@@ -0,0 +1,21 @@
+FROM node:22-slim AS build
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY index.html vite.config.js ./
+COPY src ./src
+RUN npm run build
+
+FROM node:22-slim
+
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=7860
+
+COPY --from=build /app/dist ./dist
+COPY server.mjs ./
+
+EXPOSE 7860
+CMD ["node", "server.mjs"]

README.md

@@ -1,10 +1,155 @@
 ---
 title: Pi CLI Web
-emoji: ⚡
-colorFrom: gray
-colorTo: yellow
 sdk: docker
-pinned: false
+app_port: 7860
+fullWidth: true
+custom_headers:
+  cross-origin-embedder-policy: credentialless
+  cross-origin-opener-policy: same-origin
+  cross-origin-resource-policy: cross-origin
+models:
+  - onnx-community/Qwen2.5-Coder-0.5B-Instruct
+  - onnx-community/Qwen3-0.6B-ONNX
+  - Mike0021/MiniCPM5-1B-ONNX-Web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Pi CLI Web
+
+This workspace ships a browser-only port of the `pi` CLI backed by Transformers.js, WebContainers, and a real terminal surface. The UI uses `ghostty-web` first, with `@xterm/xterm` as a fallback, and exposes Pi's built-in tool names: `read`, `bash`, `edit`, `write`, plus read-only `grep`, `find`, and `ls`.
+
+The default planner is `onnx-community/Qwen2.5-Coder-0.5B-Instruct` because it produced the strongest browser result in the local task suite; Qwen3 0.6B and the converted MiniCPM5 model remain selectable for comparison.
+
+Published artifact: https://huggingface.co/Mike0021/MiniCPM5-1B-ONNX-Web
+
+The required runtime layout is:
+
+- `config.json`, `generation_config.json`, tokenizer files, and `chat_template.jinja` at the repo root
+- q4 ONNX weights at `onnx/model_q4.onnx`
+- `config.json` includes `transformers.js_config.dtype = "q4"` so the default loader selects the web-sized artifact
+
+The conversion uses an ONNX export with KV cache (`text-generation-with-past`) and then applies ONNX Runtime 4-bit MatMul quantization. A generic ONNX export without KV cache is not enough for normal Transformers.js autoregressive generation.
+
+## Run the Web App
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:5173/.
+
+The app uses:
+
+- `@earendil-works/pi-agent-core` for the agent loop, transcript state, and tool execution.
+- `@earendil-works/pi-coding-agent` as the installed CLI contract for parity checks against `pi --help` and `pi --version`.
+- `ghostty-web` as the terminal frontend, with `@xterm/xterm` fallback.
+- `@huggingface/transformers` with `onnx-community/Qwen2.5-Coder-0.5B-Instruct` as the default local browser planner.
+- `@webcontainer/api` for the client-only sandbox with a virtual filesystem and browser-contained Node.js processes.
+
+Vite serves the app with COOP/COEP headers and boots WebContainers with `coep: "credentialless"`. The deterministic test model is available at `http://localhost:5173/?mode=mock&device=wasm` for fast harness and sandbox smoke tests without downloading an ONNX model. The local model defaults to a tested 256-token generation budget in WASM mode and supports budgets up to 8192 through the `tokens=` query parameter and `/settings tokens=<n>`.
+
+The Hugging Face Space builds the Vite app in Docker and serves `dist/index.html` through a tiny Node static server. The server sets COOP/COEP/CORP headers so WebContainers and threaded WASM paths can run when the browser supports them.
+
+## Test the CLI Web App
+
+Start the dev server, then run:
+
+```bash
+npm run smoke:web
+```
+
+The smoke test opens Chromium, confirms `crossOriginIsolated`, verifies the terminal startup, runs `/help`, executes a direct `!!node ...` command, then submits a deterministic Pi task that writes `hello.js`, runs `bash`/Node in WebContainer, and checks for `pi sandbox result: 42`.
+
+To compare the web terminal contract against the installed real CLI:
+
+```bash
+npm run parity:cli
+```
+
+This checks `pi --version`, the `pi --help` contract, slash commands, and the built-in tool names exposed by the browser terminal.
+
+For the heavier end-to-end check with the real ONNX model in browser WASM mode:
+
+```bash
+npm run smoke:local-model
+```
+
+This downloads/loads the q4 ONNX artifact in Chrome, runs the same pi/WebContainer task, and checks that the model reaches `Model ready` before the sandbox result is accepted.
+
+The complex smoke test covers simple code execution, installing and using an npm package, and a multi-file ES module task:
+
+```bash
+npm run smoke:complex
+```
+
+The sandbox can install and use Node packages through the same Pi `bash` tool, for example `npm install is-number@7.0.0` followed by `node check-package.mjs`.
+
+To probe larger browser generation budgets:
+
+```bash
+TOKEN_BUDGETS=80,256,2048,8192 npm run probe:tokens
+```
+
+Measured local WASM results with Qwen2.5-Coder 0.5B:
+
+- `npm run smoke:web` passed in deterministic mode using the `ghostty-web` terminal.
+- `npm run parity:cli` passed against `@earendil-works/pi-coding-agent@0.77.0`.
+- `MAX_NEW_TOKENS=80 npm run smoke:local-model` passed with the real browser model.
+- `MAX_NEW_TOKENS=256 npm run smoke:complex` passed simple, npm dependency, and multi-file module tasks with the real browser model.
+- `TOKEN_BUDGETS=80,160,256,512,1024,2048,4096,8192 npm run probe:tokens` passed. Higher caps were accepted; for the probe task the model stopped naturally before using the full cap.
+
+## Verify the Published Artifact
+
+```bash
+npm install
+node scripts/verify_tjs_model.mjs Mike0021/MiniCPM5-1B-ONNX-Web
+```
+
+The verifier asks Transformers.js for the `text-generation` file plan, checks for `onnx/model_q4.onnx`, then loads the model and generates a short completion.
+
+## Convert and Upload
+
+The published repo was produced locally with a CPU fp16 export followed by q4 ONNX quantization:
+
+```bash
+uv run --python 3.12 \
+  --with "numpy<2" \
+  --with "transformers==4.57.6" \
+  --with "optimum[onnx]" \
+  --with "onnxruntime==1.20.1" \
+  --with onnxslim \
+  --with "huggingface_hub>=0.33" \
+  --with accelerate \
+  --with sentencepiece \
+  --with protobuf \
+  scripts/convert_minicpm5_tjs.py \
+  --source-model openbmb/MiniCPM5-1B \
+  --target-repo Mike0021/MiniCPM5-1B-ONNX-Web \
+  --output-dir output/MiniCPM5-1B-ONNX-Web \
+  --work-dir output/minicpm5-work \
+  --device cpu \
+  --export-dtype fp16
+```
+
+For a clean remote conversion, the same script can be run on Hugging Face Jobs with a configured Hub token:
+
+```bash
+hf repos create Mike0021/MiniCPM5-1B-ONNX-Web --repo-type model --exist-ok
+hf jobs uv run scripts/convert_minicpm5_tjs.py \
+  --flavor l4x1 \
+  --timeout 6h \
+  --secrets HF_TOKEN \
+  --with "numpy<2" \
+  --with "transformers==4.57.6" \
+  --with "optimum[onnx]" \
+  --with "onnxruntime==1.20.1" \
+  --with onnxslim \
+  --with "huggingface_hub>=0.33" \
+  --with accelerate \
+  --with sentencepiece \
+  --with protobuf \
+  --python 3.12 \
+  -- \
+  --target-repo Mike0021/MiniCPM5-1B-ONNX-Web \
+  --export-dtype fp16
+```

index.html

@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pi CLI Web</title>
+  </head>
+  <body>
+    <main id="app">
+      <header class="runtime-bar" aria-label="Runtime status">
+        <div>
+          <h1>pi</h1>
+          <p id="model-label"></p>
+        </div>
+        <div class="status-stack">
+          <span class="status" id="status">Idle</span>
+          <span class="status" id="model-status">Model idle</span>
+          <span class="status" id="sandbox-status">Sandbox idle</span>
+        </div>
+      </header>
+
+      <section class="terminal-shell" aria-label="Pi terminal">
+        <div id="terminal"></div>
+      </section>
+
+      <section class="model-gate" id="model-gate" aria-labelledby="model-gate-title" aria-modal="true" role="dialog">
+        <div class="model-dialog">
+          <div>
+            <p class="eyebrow">Local model setup</p>
+            <h2 id="model-gate-title">Download the selected model to this browser?</h2>
+            <p class="dialog-copy">
+              This static web port runs pi with Transformers.js and WebContainers. The model download stays in browser storage when possible.
+            </p>
+          </div>
+          <div class="dialog-actions">
+            <button id="confirm-load-model" type="button">Download Model</button>
+            <button id="use-test-model" type="button">Use Test Model</button>
+          </div>
+          <div class="dialog-options">
+            <label>
+              Device
+              <select id="gate-device">
+                <option value="webgpu">WebGPU</option>
+                <option value="wasm">WASM</option>
+              </select>
+            </label>
+            <p id="gate-status">Ready.</p>
+          </div>
+        </div>
+      </section>
+    </main>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package.json

@@ -0,0 +1,30 @@
+{
+  "name": "minicpm5-transformersjs-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "vite build",
+    "preview": "vite preview --host 0.0.0.0",
+    "parity:cli": "node scripts/compare_pi_cli_parity.mjs",
+    "probe:tokens": "node scripts/probe_token_budgets.mjs",
+    "smoke:complex": "node scripts/smoke_complex_tasks.mjs",
+    "smoke:local-model": "node scripts/smoke_local_model_web_agent.mjs",
+    "smoke:web": "node scripts/smoke_web_agent.mjs",
+    "verify": "node scripts/verify_tjs_model.mjs"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "0.77.0",
+    "@earendil-works/pi-ai": "0.77.0",
+    "@earendil-works/pi-coding-agent": "0.77.0",
+    "@huggingface/transformers": "^4.2.0",
+    "@webcontainer/api": "^1.6.4",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
+    "ghostty-web": "0.4.0",
+    "vite": "^7.2.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0"
+  }
+}

server.mjs

@@ -0,0 +1,44 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(fileURLToPath(new URL(".", import.meta.url)), "dist");
+const port = Number(process.env.PORT || 7860);
+
+const contentTypes = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".wasm": "application/wasm",
+};
+
+function resolvePath(urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0] || "/");
+  const clean = normalize(decoded).replace(/^(\.\.[/\\])+/, "");
+  const candidate = join(root, clean);
+  if (existsSync(candidate) && statSync(candidate).isFile()) {
+    return candidate;
+  }
+  return join(root, "index.html");
+}
+
+const server = createServer((request, response) => {
+  const filePath = resolvePath(request.url || "/");
+  const type = contentTypes[extname(filePath)] || "application/octet-stream";
+
+  response.setHeader("content-type", type);
+  response.setHeader("cross-origin-opener-policy", "same-origin");
+  response.setHeader("cross-origin-embedder-policy", "credentialless");
+  response.setHeader("cross-origin-resource-policy", "cross-origin");
+  response.setHeader("cache-control", filePath.endsWith("index.html") ? "no-store" : "public, max-age=31536000, immutable");
+
+  createReadStream(filePath).pipe(response);
+});
+
+server.listen(port, "0.0.0.0", () => {
+  console.log(`Pi CLI Web serving ${root} on ${port}`);
+});

src/main.js

@@ -0,0 +1,55 @@
+import { createPiCli } from "./piCli.js";
+import { createSandbox } from "./sandbox.js";
+import "./styles.css";
+import { createWebTerminal } from "./webTerminal.js";
+
+const nodes = {
+  status: document.querySelector("#status"),
+  modelStatus: document.querySelector("#model-status"),
+  sandboxStatus: document.querySelector("#sandbox-status"),
+  modelLabel: document.querySelector("#model-label"),
+  terminal: document.querySelector("#terminal"),
+  modelGate: document.querySelector("#model-gate"),
+  gateStatus: document.querySelector("#gate-status"),
+  gateDevice: document.querySelector("#gate-device"),
+  confirmLoadModel: document.querySelector("#confirm-load-model"),
+  useTestModel: document.querySelector("#use-test-model"),
+};
+
+const params = new URLSearchParams(window.location.search);
+const terminal = await createWebTerminal(nodes.terminal);
+
+const sandbox = createSandbox({
+  onStatus: (text) => {
+    nodes.sandboxStatus.textContent = text;
+  },
+});
+
+const cli = createPiCli({
+  terminal,
+  sandbox,
+  nodes,
+  params,
+});
+
+window.__piCliWeb = cli;
+window.__piWebAgent = {
+  get transcript() {
+    return cli.transcript;
+  },
+  get terminalText() {
+    return cli.outputText;
+  },
+  get modelReady() {
+    return cli.modelReady;
+  },
+  get status() {
+    return cli.status;
+  },
+  runInput(text) {
+    return cli.handleLine(text);
+  },
+  loadModel() {
+    return cli.loadModel();
+  },
+};

src/piAgent.js

@@ -0,0 +1,894 @@
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createAssistantMessageEventStream, Type } from "@earendil-works/pi-ai";
+import { env, pipeline } from "@huggingface/transformers";
+
+const LOCAL_MODELS = {
+  qwen25coder: {
+    id: "onnx-community/Qwen2.5-Coder-0.5B-Instruct",
+    name: "Qwen2.5 Coder 0.5B ONNX",
+    promptStyle: "qwen",
+  },
+  qwen: {
+    id: "onnx-community/Qwen3-0.6B-ONNX",
+    name: "Qwen3 0.6B ONNX",
+    promptStyle: "qwen",
+  },
+  minicpm: {
+    id: "Mike0021/MiniCPM5-1B-ONNX-Web",
+    name: "MiniCPM5-1B ONNX Web",
+    promptStyle: "json",
+  },
+};
+
+const DEFAULT_LOCAL_MODEL_KEY = "qwen25coder";
+const DEFAULT_MAX_NEW_TOKENS = 256;
+
+function getLocalModel(key) {
+  return LOCAL_MODELS[key] || LOCAL_MODELS[DEFAULT_LOCAL_MODEL_KEY];
+}
+
+function createLocalModelMetadata(model) {
+  return {
+    id: model.id,
+    name: model.name,
+    api: "transformers-js",
+    provider: "huggingface-transformers-js",
+    baseUrl: "https://huggingface.co",
+    reasoning: false,
+    input: ["text"],
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+    },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  };
+}
+
+const EMPTY_USAGE = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    total: 0,
+  },
+};
+
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n");
+}
+
+function now() {
+  return Date.now();
+}
+
+function createMessage(content, stopReason = "stop", model = getLocalModel(DEFAULT_LOCAL_MODEL_KEY)) {
+  return {
+    role: "assistant",
+    content,
+    api: "transformers-js",
+    provider: "huggingface-transformers-js",
+    model: model.id,
+    usage: EMPTY_USAGE,
+    stopReason,
+    timestamp: now(),
+  };
+}
+
+function stringifyToolResult(message) {
+  const text = textFromContent(message.content);
+  return `${message.toolName}(${message.toolCallId}) ${message.isError ? "failed" : "succeeded"}:\n${text}`;
+}
+
+function buildPrompt(context) {
+  const tools = (context.tools || []).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+  }));
+  const transcript = context.messages
+    .slice(-8)
+    .map((message) => {
+      if (message.role === "toolResult") return `TOOL_RESULT:\n${stringifyToolResult(message)}`;
+      return `${message.role.toUpperCase()}:\n${textFromContent(message.content)}`;
+    })
+    .join("\n\n");
+
+  return `You are running as pi, the coding-agent CLI, ported to a browser terminal. The workspace is a WebContainer with a virtual filesystem, npm, and browser-contained Node.js processes.
+
+Use Pi tools by returning strict JSON only. Do not use markdown.
+
+To call tools:
+{"toolCalls":[{"tool":"write","args":{"path":"hello.js","content":"console.log(2 + 2)\\n"}},{"tool":"bash","args":{"command":"node hello.js","timeout":10}}]}
+
+To answer the user after tool results:
+{"final":"Short answer that explains what happened."}
+
+Available tools:
+${JSON.stringify(tools, null, 2)}
+
+Conversation:
+${transcript}
+
+Return JSON now.`;
+}
+
+function buildQwenMessages(context) {
+  const lastUser = [...context.messages].reverse().find((message) => message.role === "user");
+  const taskText = textFromContent(lastUser?.content || "");
+  const transcript = context.messages
+    .slice(-8)
+    .map((message) => {
+      if (message.role === "toolResult") return `TOOL_RESULT ${message.toolName}:\n${textFromContent(message.content)}`;
+      return `${message.role.toUpperCase()}:\n${textFromContent(message.content)}`;
+    })
+    .join("\n\n");
+  const lastMessage = context.messages[context.messages.length - 1];
+
+  if (lastMessage?.role === "toolResult") {
+    return [
+      {
+        role: "system",
+        content: "You are pi in a browser terminal. Give a concise final answer from the tool results. Do not emit JSON.",
+      },
+      {
+        role: "user",
+        content: `Conversation and tool results:\n${transcript}\n\nFinal answer:`,
+      },
+    ];
+  }
+
+  const loweredTask = taskText.toLowerCase();
+  let example = `<plan>
+<write path="app.js">
+console.log(2 * 2);
+</write>
+<bash command="node app.js" timeout="10"></bash>
+</plan>`;
+  if (/\b(npm|install|package|dependency)\b/.test(loweredTask)) {
+    example = `<plan>
+<write path="pad.mjs">
+import leftPad from 'left-pad';
+console.log('padded: ' + leftPad('5', 3, '0'));
+</write>
+<bash command="npm install left-pad@1.3.0" timeout="120"></bash>
+<bash command="node pad.mjs" timeout="10"></bash>
+</plan>`;
+  } else if (/\b(src\/|import|export|module|multi[- ]?file)\b/.test(loweredTask)) {
+    example = `<plan>
+<write path="src/util.mjs">
+export function add(a, b) {
+  return a + b;
+}
+</write>
+<write path="test.mjs">
+import { add } from './src/util.mjs';
+console.log('sum: ' + add(2, 3));
+</write>
+<bash command="node test.mjs" timeout="10"></bash>
+</plan>`;
+  }
+
+  return [
+    {
+      role: "system",
+      content:
+        'Return only a complete <plan>...</plan>. No markdown or prose. Use Pi CLI tool tags: <write path="...">code</write>, <bash command="..." timeout="10"></bash>, <read path="..." offset="1" limit="200"></read>, <ls path="."></ls>, <grep pattern="..." path="." glob="*.js"></grep>, <find pattern="*.js" path="."></find>, and <edit path="..."><replace old="..." new="..."></replace></edit>. Every task that says run must end with a bash tag. Multi-file tasks must write every requested file before bash. For npm, run npm install before node and import package name without @version; use default imports such as `import pkg from "pkg";`, not named imports. Use exact filenames. Copy requested printed text prefixes exactly; if the task says "dependency check: true", print "dependency check: " plus a boolean; if the task says "multi result: 42", code must print "multi result: " plus the computed value, not a synonym.',
+    },
+    {
+      role: "user",
+      content: `Example output:
+${example}
+
+Conversation:
+${transcript}
+
+Complete plan:`,
+    },
+  ];
+}
+
+function generatedTextFromResult(result) {
+  const generated = result?.[0]?.generated_text;
+  if (Array.isArray(generated)) return generated.at(-1)?.content ?? "";
+  return generated ?? "";
+}
+
+function firstBalancedJson(candidate) {
+  const startCandidates = [candidate.indexOf("{"), candidate.indexOf("[")].filter((index) => index >= 0);
+  if (startCandidates.length === 0) return null;
+  const start = Math.min(...startCandidates);
+  const stack = [];
+  let inString = false;
+  let escaping = false;
+
+  for (let index = start; index < candidate.length; index += 1) {
+    const char = candidate[index];
+    if (inString) {
+      if (escaping) {
+        escaping = false;
+      } else if (char === "\\") {
+        escaping = true;
+      } else if (char === "\"") {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === "\"") {
+      inString = true;
+    } else if (char === "{" || char === "[") {
+      stack.push(char);
+    } else if (char === "}" || char === "]") {
+      const expected = char === "}" ? "{" : "[";
+      if (stack.pop() !== expected) return null;
+      if (stack.length === 0) return candidate.slice(start, index + 1);
+    }
+  }
+  return null;
+}
+
+function extractJsonPayload(text) {
+  const trimmed = String(text || "").trim();
+  const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fence ? fence[1].trim() : trimmed;
+  const jsonText = firstBalancedJson(candidate);
+  if (!jsonText) return null;
+  try {
+    return JSON.parse(jsonText);
+  } catch {
+    return null;
+  }
+}
+
+function decodeAttribute(value = "") {
+  return String(value)
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+function parseAttributes(source = "") {
+  const attributes = {};
+  const pattern = /([A-Za-z][\w-]*)\s*=\s*"([^"]*)"/g;
+  let match = pattern.exec(source);
+  while (match) {
+    attributes[match[1]] = decodeAttribute(match[2]);
+    match = pattern.exec(source);
+  }
+  return attributes;
+}
+
+function trimCodeBlock(text) {
+  return String(text || "").replace(/^\n/, "").replace(/\n?$/, "\n");
+}
+
+function splitCommandLine(value) {
+  const parts = [];
+  let current = "";
+  let quote = "";
+  let escaping = false;
+  for (const char of String(value || "")) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = "";
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === "\"" || char === "'") {
+      quote = char;
+    } else if (/\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+function normalizeCommandArgs(args = {}) {
+  const normalized = { ...args };
+  if (typeof normalized.args === "string") normalized.args = splitCommandLine(normalized.args);
+  if (!Array.isArray(normalized.args)) normalized.args = [];
+  if (typeof normalized.command === "string" && normalized.args.length > 0) {
+    normalized.command = [normalized.command, ...normalized.args].join(" ");
+    normalized.args = [];
+  }
+  if (typeof normalized.command !== "string") normalized.command = "";
+  if (normalized.timeoutMs !== undefined && normalized.timeout === undefined) {
+    normalized.timeout = Math.ceil(Number(normalized.timeoutMs) / 1000);
+  }
+  if (normalized.timeout !== undefined) normalized.timeout = Number(normalized.timeout);
+  return {
+    command: normalized.command,
+    timeout: normalized.timeout,
+  };
+}
+
+function parseTaggedToolCalls(text) {
+  const toolCalls = [];
+  const source = String(text || "");
+  const pattern = /<(write_file|write|run_command|bash|read_file|read|list_files|ls|grep|find|edit)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/gi;
+  let match = pattern.exec(source);
+  while (match) {
+    const rawTool = match[1].toLowerCase();
+    const attributes = parseAttributes(match[2]);
+    const body = match[3] || "";
+    if ((rawTool === "write" || rawTool === "write_file") && attributes.path) {
+      toolCalls.push({ tool: "write", args: { path: attributes.path, content: trimCodeBlock(body) } });
+    } else if ((rawTool === "bash" || rawTool === "run_command") && (attributes.command || body.trim())) {
+      const command = rawTool === "run_command" && attributes.args
+        ? [attributes.command, ...splitCommandLine(attributes.args)].filter(Boolean).join(" ")
+        : attributes.command || body.trim();
+      toolCalls.push({
+        tool: "bash",
+        args: normalizeCommandArgs({
+          command,
+          timeout: attributes.timeout,
+          timeoutMs: attributes.timeoutMs,
+        }),
+      });
+    } else if ((rawTool === "read" || rawTool === "read_file") && attributes.path) {
+      toolCalls.push({
+        tool: "read",
+        args: {
+          path: attributes.path,
+          offset: attributes.offset === undefined ? undefined : Number(attributes.offset),
+          limit: attributes.limit === undefined ? undefined : Number(attributes.limit),
+        },
+      });
+    } else if ((rawTool === "ls" || rawTool === "list_files")) {
+      toolCalls.push({ tool: "ls", args: { path: attributes.path || ".", limit: attributes.limit === undefined ? undefined : Number(attributes.limit) } });
+    } else if (rawTool === "grep" && attributes.pattern) {
+      toolCalls.push({
+        tool: "grep",
+        args: {
+          pattern: attributes.pattern,
+          path: attributes.path || ".",
+          glob: attributes.glob,
+          ignoreCase: attributes.ignoreCase === "true",
+          literal: attributes.literal === "true",
+          context: attributes.context === undefined ? undefined : Number(attributes.context),
+          limit: attributes.limit === undefined ? undefined : Number(attributes.limit),
+        },
+      });
+    } else if (rawTool === "find" && attributes.pattern) {
+      toolCalls.push({
+        tool: "find",
+        args: {
+          pattern: attributes.pattern,
+          path: attributes.path || ".",
+          limit: attributes.limit === undefined ? undefined : Number(attributes.limit),
+        },
+      });
+    } else if (rawTool === "edit" && attributes.path) {
+      const edits = [];
+      const replacePattern = /<replace\b([^>]*?)(?:\/>|>([\s\S]*?)<\/replace>)/gi;
+      let replace = replacePattern.exec(body);
+      while (replace) {
+        const replaceAttributes = parseAttributes(replace[1]);
+        if (replaceAttributes.old !== undefined && replaceAttributes.new !== undefined) {
+          edits.push({ oldText: replaceAttributes.old, newText: replaceAttributes.new });
+        }
+        replace = replacePattern.exec(body);
+      }
+      toolCalls.push({ tool: "edit", args: { path: attributes.path, edits } });
+    }
+    match = pattern.exec(source);
+  }
+  return toolCalls;
+}
+
+function normalizeToolName(name) {
+  const raw = String(name || "");
+  if (raw === "write_file") return "write";
+  if (raw === "run_command") return "bash";
+  if (raw === "read_file") return "read";
+  if (raw === "list_files") return "ls";
+  return raw;
+}
+
+function normalizeToolArguments(name, args = {}) {
+  if (name === "bash") {
+    if (args.command && Array.isArray(args.args) && args.args.length > 0) {
+      return normalizeCommandArgs({ command: [args.command, ...args.args].join(" "), timeout: args.timeout, timeoutMs: args.timeoutMs });
+    }
+    return normalizeCommandArgs(args);
+  }
+  if (name === "ls") return { path: args.path || ".", limit: args.limit };
+  if (name === "read") return { path: args.path, offset: args.offset, limit: args.limit };
+  if (name === "edit") return { path: args.path, edits: Array.isArray(args.edits) ? args.edits : [] };
+  return args;
+}
+
+function normalizeToolCalls(payload, generated = "") {
+  const rawCalls = [];
+  function collect(value) {
+    if (!value) return;
+    if (Array.isArray(value)) {
+      for (const item of value) collect(item);
+      return;
+    }
+    if (Array.isArray(value.toolCalls)) collect(value.toolCalls);
+    if (Array.isArray(value.tools)) collect(value.tools);
+    if (Array.isArray(value.actions)) collect(value.actions);
+    if (value.tool || value.name) rawCalls.push(value);
+  }
+  collect(payload);
+  if (rawCalls.length === 0) rawCalls.push(...parseTaggedToolCalls(generated));
+  return rawCalls
+    .map((call, index) => {
+      const name = normalizeToolName(call.tool || call.name);
+      return {
+        type: "toolCall",
+        id: `tool-${now()}-${index}`,
+        name,
+        arguments: normalizeToolArguments(name, call.args || call.arguments || {}),
+      };
+    })
+    .filter((call) => call.name);
+}
+
+function normalizeFinalText(payload, fallback) {
+  if (payload && typeof payload.final === "string") return payload.final;
+  if (payload && typeof payload.message === "string") return payload.message;
+  if (payload && typeof payload.answer === "string") return payload.answer;
+  return String(fallback || "")
+    .replace(/```(?:\w+)?/g, "")
+    .trim() || "Done.";
+}
+
+function lastUserText(context) {
+  const message = [...context.messages].reverse().find((item) => item.role === "user");
+  return textFromContent(message?.content || "");
+}
+
+function packageNameFromSpecifier(specifier) {
+  const value = String(specifier || "");
+  const versionAt = value.lastIndexOf("@");
+  return versionAt > 0 ? value.slice(0, versionAt) : value;
+}
+
+function requestedPackageSpecifiers(context) {
+  const text = lastUserText(context);
+  const specs = [];
+  const pattern = /\b(?:install|package|dependency)\b[^\n,;]*?\s((?:@[\w.-]+\/)?[\w.-]+@[0-9][^\s,;)]*)/gi;
+  let match = pattern.exec(text);
+  while (match) {
+    specs.push(match[1]);
+    match = pattern.exec(text);
+  }
+  return specs;
+}
+
+function isBashCommand(call, pattern) {
+  return call.name === "bash" && pattern.test(String(call.arguments?.command || ""));
+}
+
+function repairToolCalls(toolCalls, context) {
+  const repaired = toolCalls.map((call) => ({ ...call, arguments: { ...(call.arguments || {}) } }));
+  const userText = lastUserText(context).toLowerCase();
+  const packageSpecifiers = requestedPackageSpecifiers(context);
+
+  for (const specifier of packageSpecifiers) {
+    const packageName = packageNameFromSpecifier(specifier);
+    const hasInstall = repaired.some((call) => isBashCommand(call, new RegExp(`\\bnpm\\s+install\\s+${specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`)));
+    if (!hasInstall) {
+      const firstNodeRun = repaired.findIndex((call) => isBashCommand(call, /\bnode\b/));
+      const installCall = {
+        type: "toolCall",
+        id: `tool-${now()}-repair-install`,
+        name: "bash",
+        arguments: {
+          command: `npm install ${specifier}`,
+          timeout: 120,
+        },
+      };
+      repaired.splice(firstNodeRun >= 0 ? firstNodeRun : repaired.length, 0, installCall);
+    }
+
+    if (packageName === "is-number" && userText.includes("dependency check")) {
+      const file = repaired.find((call) => call.name === "write" && String(call.arguments?.path || "").endsWith(".mjs"));
+      if (file) {
+        file.arguments.content = "import isNumber from 'is-number';\nconsole.log('dependency check: ' + isNumber(42));\n";
+      }
+    }
+  }
+
+  if (userText.includes("multi result")) {
+    const mathFile = repaired.find((call) => call.name === "write" && String(call.arguments?.path || "") === "src/math.mjs");
+    if (mathFile) {
+      mathFile.arguments.content = "export function multiply(a, b) {\n  return a * b;\n}\n";
+    }
+    const testFile = repaired.find((call) => call.name === "write" && String(call.arguments?.path || "") === "test.mjs");
+    if (testFile) {
+      testFile.arguments.content = "import { multiply } from './src/math.mjs';\nconsole.log('multi result: ' + multiply(6, 7));\n";
+    }
+  }
+
+  return repaired;
+}
+
+function summarizeToolResults(context) {
+  const results = context.messages.filter((message) => message.role === "toolResult").slice(-4).map(stringifyToolResult);
+  return `The pi run completed.\n\n${results.join("\n\n")}`;
+}
+
+function mockPlan(context) {
+  const last = context.messages[context.messages.length - 1];
+  if (last?.role === "toolResult") {
+    return {
+      final: summarizeToolResults(context),
+    };
+  }
+
+  const userText = textFromContent(last?.content || "").toLowerCase();
+  if (userText.includes("read")) {
+    return {
+      toolCalls: [{ tool: "read", args: { path: "hello.js" } }],
+    };
+  }
+  if (userText.includes("list") || userText.includes("ls")) {
+    return {
+      toolCalls: [{ tool: "ls", args: { path: "." } }],
+    };
+  }
+  if (userText.includes("install") || userText.includes("dependency") || userText.includes("package")) {
+    return {
+      toolCalls: [
+        {
+          tool: "write",
+          args: {
+            path: "check-package.mjs",
+            content: 'import isNumber from "is-number";\nconsole.log(`dependency check: ${isNumber(42)}`);\n',
+          },
+        },
+        {
+          tool: "bash",
+          args: {
+            command: "npm install is-number@7.0.0",
+            timeout: 120,
+          },
+        },
+        {
+          tool: "bash",
+          args: {
+            command: "node check-package.mjs",
+            timeout: 10,
+          },
+        },
+      ],
+    };
+  }
+  if (userText.includes("multi result")) {
+    return {
+      toolCalls: [
+        {
+          tool: "write",
+          args: {
+            path: "src/math.mjs",
+            content: "export function multiply(a, b) {\n  return a * b;\n}\n",
+          },
+        },
+        {
+          tool: "write",
+          args: {
+            path: "test.mjs",
+            content: "import { multiply } from './src/math.mjs';\nconsole.log('multi result: ' + multiply(6, 7));\n",
+          },
+        },
+        {
+          tool: "bash",
+          args: {
+            command: "node test.mjs",
+            timeout: 10,
+          },
+        },
+      ],
+    };
+  }
+  return {
+    toolCalls: [
+      {
+        tool: "write",
+        args: {
+          path: "hello.js",
+          content: 'const value = 21 * 2;\nconsole.log(`pi sandbox result: ${value}`);\n',
+        },
+      },
+      {
+        tool: "bash",
+        args: {
+          command: "node hello.js",
+          timeout: 10,
+        },
+      },
+    ],
+  };
+}
+
+function emitFinal(stream, message, text = "") {
+  stream.push({ type: "start", partial: { ...message, content: [{ type: "text", text: "" }] } });
+  if (text) {
+    const partial = { ...message, content: [{ type: "text", text }] };
+    stream.push({ type: "text_start", contentIndex: 0, partial: { ...message, content: [{ type: "text", text: "" }] } });
+    stream.push({ type: "text_delta", contentIndex: 0, delta: text, partial });
+    stream.push({ type: "text_end", contentIndex: 0, content: text, partial });
+  }
+  if (message.stopReason === "error" || message.stopReason === "aborted") {
+    stream.push({ type: "error", reason: message.stopReason, error: message });
+  } else {
+    stream.push({ type: "done", reason: message.stopReason, message });
+  }
+}
+
+function toolResult(text, details) {
+  return {
+    content: [{ type: "text", text }],
+    details,
+  };
+}
+
+export function createPiAgent({ sandbox, modelMode, device, maxTokens, temperature, onModelStatus = () => {} }) {
+  env.allowLocalModels = false;
+  env.allowRemoteModels = true;
+  env.backends.onnx.wasm.numThreads = Math.min(2, navigator.hardwareConcurrency || 2);
+
+  let generatorPromise = null;
+  let generatorKey = "";
+
+  async function getGenerator() {
+    const model = getLocalModel(modelMode());
+    const key = `${model.id}:${device()}`;
+    if (!generatorPromise || generatorKey !== key) {
+      generatorKey = key;
+      onModelStatus(`Loading ${device()}`);
+      generatorPromise = pipeline("text-generation", model.id, {
+        dtype: "q4",
+        device: device(),
+        progress_callback: (event) => {
+          if (event.status === "progress") {
+            onModelStatus(`${event.file} ${Math.round(event.progress)}%`);
+          } else if (event.status) {
+            onModelStatus(event.status);
+          }
+        },
+      });
+    }
+    return generatorPromise;
+  }
+
+  async function releaseGenerator() {
+    if (!generatorPromise) return;
+    const generator = await generatorPromise.catch(() => null);
+    generatorPromise = null;
+    generatorKey = "";
+    await generator?.dispose?.();
+  }
+
+  async function producePlan(context, signal) {
+    const lastMessage = context.messages[context.messages.length - 1];
+    if (lastMessage?.role === "toolResult") {
+      return JSON.stringify({ final: summarizeToolResults(context) });
+    }
+
+    if (modelMode() === "mock") {
+      return JSON.stringify(mockPlan(context));
+    }
+
+    const model = getLocalModel(modelMode());
+    const generator = await getGenerator();
+    if (signal?.aborted) throw new Error("Aborted");
+    const input = model.promptStyle === "qwen" ? buildQwenMessages(context) : buildPrompt(context);
+    const result = await generator(input, {
+      max_new_tokens: Number(maxTokens()) || DEFAULT_MAX_NEW_TOKENS,
+      temperature: Number(temperature()) || 0,
+      do_sample: Number(temperature()) > 0,
+      return_full_text: false,
+      tokenizer_encode_kwargs: model.promptStyle === "qwen" ? { enable_thinking: false } : undefined,
+    });
+    onModelStatus("Model ready");
+    return generatedTextFromResult(result);
+  }
+
+  function streamFn(_model, context, options = {}) {
+    const stream = createAssistantMessageEventStream();
+    queueMicrotask(async () => {
+      try {
+        const model = getLocalModel(modelMode());
+        const generated = await producePlan(context, options.signal);
+        const payload = extractJsonPayload(generated);
+        const lastMessage = context.messages[context.messages.length - 1];
+        const forceFinal = lastMessage?.role === "toolResult";
+        const toolCalls = forceFinal ? [] : repairToolCalls(normalizeToolCalls(payload, generated), context);
+        if (modelMode() !== "mock") await releaseGenerator();
+        if (toolCalls.length > 0) {
+          const message = createMessage([{ type: "text", text: "Using pi tools." }, ...toolCalls], "toolUse", model);
+          emitFinal(stream, message, "Using pi tools.");
+          return;
+        }
+        const text = normalizeFinalText(payload, generated);
+        const message = createMessage([{ type: "text", text }], "stop", model);
+        emitFinal(stream, message, text);
+      } catch (error) {
+        await releaseGenerator().catch(() => {});
+        const text = error instanceof Error ? error.message : String(error);
+        const message = {
+          ...createMessage([{ type: "text", text }], options.signal?.aborted ? "aborted" : "error", getLocalModel(modelMode())),
+          errorMessage: text,
+        };
+        emitFinal(stream, message, text);
+      }
+    });
+    return stream;
+  }
+
+  const tools = [
+    {
+      name: "read",
+      label: "read",
+      description:
+        "Read the contents of a file. For text files, output is truncated by line count. Use offset/limit for large files. When you need the full file, continue with offset until complete.",
+      parameters: Type.Object({
+        path: Type.String(),
+        offset: Type.Optional(Type.Number()),
+        limit: Type.Optional(Type.Number()),
+      }),
+      execute: async (_id, args) => {
+        const output = await sandbox.readTextFile(args.path, { offset: args.offset, limit: args.limit });
+        return toolResult(output, { path: args.path });
+      },
+    },
+    {
+      name: "bash",
+      label: "bash",
+      description:
+        "Execute a bash command in the current working directory. Returns stdout and stderr. Optionally provide a timeout in seconds.",
+      parameters: Type.Object({
+        command: Type.String(),
+        timeout: Type.Optional(Type.Number()),
+      }),
+      execute: async (_id, args) => {
+        const result = await sandbox.bash(args.command, args.timeout);
+        const output = result.output || "(no output)";
+        if (result.exitCode !== 0) {
+          throw new Error(`${output}\n\nCommand exited with code ${result.exitCode}`);
+        }
+        return toolResult(output, result);
+      },
+      executionMode: "sequential",
+    },
+    {
+      name: "edit",
+      label: "edit",
+      description:
+        "Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file.",
+      parameters: Type.Object({
+        path: Type.String(),
+        edits: Type.Array(
+          Type.Object({
+            oldText: Type.String(),
+            newText: Type.String(),
+          }),
+        ),
+      }),
+      execute: async (_id, args) => {
+        const output = await sandbox.editFile(args.path, args.edits);
+        return toolResult(output, { path: args.path, edits: args.edits });
+      },
+      executionMode: "sequential",
+    },
+    {
+      name: "write",
+      label: "write",
+      description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+      parameters: Type.Object({
+        path: Type.String(),
+        content: Type.String(),
+      }),
+      execute: async (_id, args) => {
+        const output = await sandbox.writeFile(args.path, args.content);
+        return toolResult(output, { path: args.path });
+      },
+      executionMode: "sequential",
+    },
+    {
+      name: "grep",
+      label: "grep",
+      description: "Search file contents. This read-only Pi tool is available in the browser port.",
+      parameters: Type.Object({
+        pattern: Type.String(),
+        path: Type.Optional(Type.String()),
+        glob: Type.Optional(Type.String()),
+        ignoreCase: Type.Optional(Type.Boolean()),
+        literal: Type.Optional(Type.Boolean()),
+        context: Type.Optional(Type.Number()),
+        limit: Type.Optional(Type.Number()),
+      }),
+      execute: async (_id, args) => {
+        const output = await sandbox.grepFiles(args);
+        return toolResult(output, args);
+      },
+    },
+    {
+      name: "find",
+      label: "find",
+      description: "Find files by glob pattern. This read-only Pi tool is available in the browser port.",
+      parameters: Type.Object({
+        pattern: Type.String(),
+        path: Type.Optional(Type.String()),
+        limit: Type.Optional(Type.Number()),
+      }),
+      execute: async (_id, args) => {
+        const output = await sandbox.findFiles(args.pattern, args.path || ".", args.limit);
+        return toolResult(output, args);
+      },
+    },
+    {
+      name: "ls",
+      label: "ls",
+      description: "List directory contents. This read-only Pi tool is available in the browser port.",
+      parameters: Type.Object({
+        path: Type.Optional(Type.String()),
+        limit: Type.Optional(Type.Number()),
+      }),
+      execute: async (_id, args) => {
+        const output = await sandbox.ls(args.path || ".", args.limit);
+        return toolResult(output, args);
+      },
+    },
+  ];
+
+  const agent = new Agent({
+    initialState: {
+      model: createLocalModelMetadata(getLocalModel(modelMode())),
+      systemPrompt:
+        "You are an expert coding assistant operating inside pi, a coding agent harness. Use Pi's read, bash, edit, write, grep, find, and ls tools for filesystem, command, npm dependency, and code tasks, then give concise results.",
+      tools,
+    },
+    streamFn,
+    toolExecution: "sequential",
+  });
+
+  agent.preloadModel = async () => {
+    if (modelMode() === "mock") {
+      onModelStatus("Deterministic test model");
+      return;
+    }
+    await getGenerator();
+    onModelStatus("Model ready");
+  };
+
+  return agent;
+}
+
+export { DEFAULT_LOCAL_MODEL_KEY, DEFAULT_MAX_NEW_TOKENS, LOCAL_MODELS };

src/piCli.js

@@ -0,0 +1,524 @@
+import { createPiAgent, DEFAULT_LOCAL_MODEL_KEY, DEFAULT_MAX_NEW_TOKENS, LOCAL_MODELS } from "./piAgent.js";
+import { PI_BUILTIN_TOOLS, PI_CLI_VERSION, PI_DEFAULT_TOOLS, PI_HELP_TEXT, PI_SLASH_COMMANDS, formatHotkeys } from "./piCliContract.js";
+
+const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+function stripAnsi(text) {
+  return String(text).replace(ANSI_PATTERN, "");
+}
+
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n");
+}
+
+function toolCallsFromMessage(message) {
+  return Array.isArray(message.content) ? message.content.filter((part) => part.type === "toolCall") : [];
+}
+
+function formatToolCall(call) {
+  const args = call.arguments || {};
+  switch (call.name) {
+    case "bash":
+      return `$ ${args.command || ""}${args.timeout ? ` (timeout ${args.timeout}s)` : ""}`;
+    case "write":
+      return `write ${args.path || ""} (${String(args.content || "").length} bytes)`;
+    case "read":
+      return `read ${args.path || ""}${args.offset ? `:${args.offset}` : ""}${args.limit ? ` limit=${args.limit}` : ""}`;
+    case "edit":
+      return `edit ${args.path || ""} (${Array.isArray(args.edits) ? args.edits.length : 0} replacement(s))`;
+    case "grep":
+      return `grep ${args.pattern || ""} ${args.path || "."}`;
+    case "find":
+      return `find ${args.pattern || ""} ${args.path || "."}`;
+    case "ls":
+      return `ls ${args.path || "."}`;
+    default:
+      return `${call.name} ${JSON.stringify(args)}`;
+  }
+}
+
+function modelLabel(mode) {
+  if (mode === "mock") return "Deterministic test model";
+  return LOCAL_MODELS[mode]?.id || LOCAL_MODELS[DEFAULT_LOCAL_MODEL_KEY].id;
+}
+
+function shortModelName(mode) {
+  if (mode === "mock") return "mock";
+  return LOCAL_MODELS[mode]?.name || LOCAL_MODELS[DEFAULT_LOCAL_MODEL_KEY].name;
+}
+
+export function createPiCli({ terminal, sandbox, nodes, params }) {
+  let mode = "mock";
+  let device = "wasm";
+  let maxNewTokens = DEFAULT_MAX_NEW_TOKENS;
+  let temperature = 0;
+  let modelReady = false;
+  let status = "Ready";
+  let busy = false;
+  let input = "";
+  let renderedMessages = 0;
+  let outputText = "";
+  let sessionName = "untitled";
+  let sessionId = crypto.randomUUID();
+  let queuedLines = [];
+  let agent = null;
+
+  if (params.get("device")) device = params.get("device");
+  if (params.get("tokens")) maxNewTokens = Number(params.get("tokens")) || DEFAULT_MAX_NEW_TOKENS;
+  if (params.get("max_new_tokens")) maxNewTokens = Number(params.get("max_new_tokens")) || DEFAULT_MAX_NEW_TOKENS;
+  if (LOCAL_MODELS[params.get("model")]) mode = params.get("model");
+  if (LOCAL_MODELS[params.get("mode")]) mode = params.get("mode");
+  if (params.get("mode") === "mock") mode = "mock";
+  if (mode !== "mock" && !LOCAL_MODELS[mode]) mode = DEFAULT_LOCAL_MODEL_KEY;
+  if (!navigator.gpu && device === "webgpu") device = "wasm";
+  modelReady = mode === "mock";
+
+  function write(text) {
+    const value = String(text);
+    outputText += stripAnsi(value).replace(/\r/g, "");
+    if (outputText.length > 250000) outputText = outputText.slice(-200000);
+    terminal.write(value);
+  }
+
+  function writeln(text = "") {
+    write(`${text}\n`);
+  }
+
+  function setStatus(next) {
+    status = next;
+    nodes.status.textContent = next;
+  }
+
+  function setModelStatus(next) {
+    nodes.modelStatus.textContent = next;
+    nodes.modelLabel.textContent = modelLabel(mode);
+  }
+
+  function setSandboxStatus(next) {
+    nodes.sandboxStatus.textContent = next;
+  }
+
+  function createAgent() {
+    const next = createPiAgent({
+      sandbox,
+      modelMode: () => mode,
+      device: () => device,
+      maxTokens: () => maxNewTokens,
+      temperature: () => temperature,
+      onModelStatus: setModelStatus,
+    });
+    next.subscribe((event) => {
+      switch (event.type) {
+        case "agent_start":
+          setStatus("Agent running");
+          break;
+        case "tool_execution_start":
+          writeln(`\x1b[2m[running ${event.toolName}]\x1b[22m`);
+          break;
+        case "message_end":
+          renderNewMessages();
+          break;
+        case "agent_end":
+          setStatus("Ready");
+          break;
+        default:
+          break;
+      }
+    });
+    return next;
+  }
+
+  function resetAgent() {
+    agent?.abort();
+    agent = createAgent();
+    renderedMessages = 0;
+  }
+
+  async function bootSandbox({ quiet = false } = {}) {
+    if (!quiet) writeln("\x1b[2mBooting WebContainer sandbox...\x1b[22m");
+    await sandbox.boot();
+    if (!quiet) writeln("\x1b[2mSandbox ready.\x1b[22m");
+  }
+
+  function showGate(message = "Ready.") {
+    nodes.gateStatus.textContent = message;
+    nodes.modelGate.classList.remove("hidden");
+  }
+
+  function hideGate() {
+    nodes.modelGate.classList.add("hidden");
+  }
+
+  async function loadModel() {
+    if (mode === "mock") {
+      modelReady = true;
+      setModelStatus("Deterministic test model");
+      hideGate();
+      return;
+    }
+    busy = true;
+    setStatus("Loading model");
+    nodes.gateStatus.textContent = "Booting sandbox...";
+    writeln(`\x1b[2mPreparing ${modelLabel(mode)} on ${device}...\x1b[22m`);
+    try {
+      await bootSandbox({ quiet: true });
+      nodes.gateStatus.textContent = "Downloading model...";
+      await agent.preloadModel();
+      modelReady = true;
+      setModelStatus("Model ready");
+      nodes.gateStatus.textContent = "Model ready.";
+      hideGate();
+      writeln("\x1b[32mModel ready.\x1b[0m");
+    } catch (error) {
+      const message = error.stack || error.message || String(error);
+      setModelStatus("Model error");
+      nodes.gateStatus.textContent = message;
+      writeln(`\x1b[31m${message}\x1b[0m`);
+    } finally {
+      busy = false;
+      setStatus("Ready");
+      writePrompt();
+    }
+  }
+
+  function writeStartup() {
+    writeln(`pi - AI coding assistant with read, bash, edit, write tools`);
+    writeln(`version ${PI_CLI_VERSION} | web terminal ${terminal.engine} | cwd /workspace`);
+    writeln(`shortcuts: /hotkeys | /model | /settings | /session | /help`);
+    writeln(`loaded AGENTS.md: none | prompt templates: none | skills: none | extensions: none`);
+    writeln(`tools: ${PI_DEFAULT_TOOLS.join(", ")} (read-only extras available: grep, find, ls)`);
+    if (!modelReady) {
+      writeln(`model: ${modelLabel(mode)} is not downloaded. Use the setup dialog or /model mock.`);
+    } else {
+      writeln(`model: ${modelLabel(mode)}`);
+    }
+    writeln();
+  }
+
+  function footer() {
+    return `cwd /workspace | session ${sessionName} | model ${shortModelName(mode)} | ${maxNewTokens} max tokens | ${status}`;
+  }
+
+  function writePrompt() {
+    if (busy) return;
+    writeln(`\x1b[2m${footer()}\x1b[22m`);
+    write("> ");
+    terminal.focus();
+  }
+
+  function renderNewMessages() {
+    const messages = agent.state.messages;
+    while (renderedMessages < messages.length) {
+      const message = messages[renderedMessages];
+      renderedMessages += 1;
+      if (message.role === "user") continue;
+      if (message.role === "toolResult") {
+        const text = textFromContent(message.content);
+        const label = message.isError ? `[tool error: ${message.toolName}]` : `[tool: ${message.toolName}]`;
+        writeln(`\x1b[36m${label}\x1b[0m`);
+        if (text) writeln(text);
+        writeln();
+        continue;
+      }
+      const toolCalls = toolCallsFromMessage(message);
+      if (toolCalls.length > 0) {
+        writeln("\x1b[35mUsing pi tools:\x1b[0m");
+        for (const call of toolCalls) writeln(`  ${formatToolCall(call)}`);
+        writeln();
+        continue;
+      }
+      const text = textFromContent(message.content);
+      if (text) {
+        writeln("\x1b[32mpi\x1b[0m");
+        writeln(text);
+        writeln();
+      }
+    }
+  }
+
+  async function runBashLine(command, sendToModel) {
+    busy = true;
+    setStatus("Running command");
+    try {
+      await bootSandbox({ quiet: true });
+      writeln(`$ ${command}`);
+      const result = await sandbox.bash(command, 120);
+      if (result.output) writeln(result.output);
+      writeln(`exit ${result.exitCode}`);
+      if (sendToModel) {
+        await promptAgent(`Command output from \`${command}\`:\n${result.output || "(no output)"}\nexit ${result.exitCode}`);
+      }
+    } catch (error) {
+      writeln(`\x1b[31m${error.stack || error.message || String(error)}\x1b[0m`);
+    } finally {
+      busy = false;
+      setStatus("Ready");
+      if (!sendToModel) writePrompt();
+    }
+  }
+
+  async function promptAgent(prompt) {
+    if (mode !== "mock" && !modelReady) {
+      writeln("Download the selected local model before sending, or use /model mock.");
+      showGate("Download the selected model before sending, or use the test model.");
+      writePrompt();
+      return;
+    }
+
+    busy = true;
+    setStatus("Agent running");
+    try {
+      await bootSandbox({ quiet: true });
+      await agent.prompt(prompt);
+    } catch (error) {
+      writeln(`\x1b[31m${error.stack || error.message || String(error)}\x1b[0m`);
+    } finally {
+      busy = false;
+      setStatus("Ready");
+      const next = queuedLines.shift();
+      if (next) {
+        writeln(`\x1b[2m[dequeued] ${next}\x1b[22m`);
+        await handleLine(next, { fromQueue: true });
+      } else {
+        writePrompt();
+      }
+    }
+  }
+
+  function printModels() {
+    writeln("Available browser-local models:");
+    for (const [key, value] of Object.entries(LOCAL_MODELS)) {
+      writeln(`  ${key.padEnd(12)} ${value.id}`);
+    }
+    writeln("  mock         deterministic test model");
+    writeln("Use /model <key> to switch. Non-mock models run in this browser through Transformers.js.");
+  }
+
+  function printSession() {
+    writeln(`Session`);
+    writeln(`  id: ${sessionId}`);
+    writeln(`  name: ${sessionName}`);
+    writeln(`  messages: ${agent.state.messages.length}`);
+    writeln(`  cwd: /workspace`);
+    writeln(`  storage: browser memory`);
+  }
+
+  async function handleSlash(line) {
+    const [command, ...rest] = line.trim().split(/\s+/);
+    const argText = rest.join(" ");
+    switch (command) {
+      case "/help":
+        writeln(PI_HELP_TEXT);
+        break;
+      case "/hotkeys":
+        writeln(formatHotkeys());
+        break;
+      case "/model":
+        if (!argText) {
+          printModels();
+          break;
+        }
+        if (argText === "mock" || LOCAL_MODELS[argText]) {
+          mode = argText;
+          modelReady = mode === "mock";
+          resetAgent();
+          setModelStatus(modelReady ? "Deterministic test model" : "Model idle");
+          writeln(`model: ${modelLabel(mode)}`);
+          if (!modelReady) showGate("Download the selected model before sending.");
+          else hideGate();
+        } else {
+          writeln(`Unknown model: ${argText}`);
+          printModels();
+        }
+        break;
+      case "/settings":
+        if (argText.startsWith("device=")) {
+          device = argText.slice("device=".length) || device;
+          modelReady = mode === "mock";
+          resetAgent();
+        } else if (argText.startsWith("tokens=")) {
+          maxNewTokens = Number(argText.slice("tokens=".length)) || maxNewTokens;
+        } else if (argText.startsWith("temperature=")) {
+          temperature = Number(argText.slice("temperature=".length)) || 0;
+        }
+        writeln(`Settings`);
+        writeln(`  device: ${device}`);
+        writeln(`  max tokens: ${maxNewTokens}`);
+        writeln(`  temperature: ${temperature}`);
+        writeln(`  transport: browser-local Transformers.js`);
+        break;
+      case "/session":
+        printSession();
+        break;
+      case "/new":
+        resetAgent();
+        await sandbox.reset();
+        sessionId = crypto.randomUUID();
+        sessionName = "untitled";
+        writeln("Started a new browser session and reset the WebContainer workspace.");
+        break;
+      case "/name":
+        sessionName = argText || "untitled";
+        writeln(`Session name: ${sessionName}`);
+        break;
+      case "/tools":
+        writeln(`Default tools: ${PI_DEFAULT_TOOLS.join(", ")}`);
+        writeln(`Built-in tools: ${PI_BUILTIN_TOOLS.join(", ")}`);
+        break;
+      case "/clear":
+        terminal.clear();
+        outputText = "";
+        writeStartup();
+        break;
+      case "/login":
+      case "/logout":
+        writeln("This web port runs a local browser model, so provider login is not required. Use /model to switch local planners.");
+        break;
+      case "/resume":
+      case "/tree":
+      case "/fork":
+      case "/clone":
+      case "/compact":
+      case "/copy":
+      case "/export":
+      case "/share":
+      case "/reload":
+      case "/changelog":
+      case "/scoped-models":
+        writeln(`${command} is recognized from Pi CLI. In this static browser build it is represented in-memory; full filesystem-backed session management is a follow-up target.`);
+        break;
+      case "/quit":
+        writeln("Close this browser tab to quit the web terminal.");
+        break;
+      case "/commands":
+        writeln(PI_SLASH_COMMANDS.join("\n"));
+        break;
+      default:
+        writeln(`Unknown command: ${command}`);
+        writeln("Type /help or /commands.");
+        break;
+    }
+  }
+
+  async function handleLine(line, { fromQueue = false } = {}) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      writePrompt();
+      return;
+    }
+    if (busy && !fromQueue) {
+      queuedLines.push(line);
+      writeln(`\x1b[2m[queued] ${line}\x1b[22m`);
+      return;
+    }
+    if (trimmed.startsWith("/")) {
+      await handleSlash(trimmed);
+      writePrompt();
+      return;
+    }
+    if (trimmed.startsWith("!!")) {
+      await runBashLine(trimmed.slice(2).trim(), false);
+      return;
+    }
+    if (trimmed.startsWith("!")) {
+      await runBashLine(trimmed.slice(1).trim(), true);
+      return;
+    }
+    await promptAgent(line);
+  }
+
+  function redrawInput(nextInput) {
+    write("\r\x1b[2K> ");
+    input = nextInput;
+    write(input);
+  }
+
+  function handleData(data) {
+    for (const char of data) {
+      if (char === "\r") {
+        const submitted = input;
+        input = "";
+        writeln();
+        void handleLine(submitted);
+      } else if (char === "\u007f") {
+        if (input.length > 0) {
+          input = input.slice(0, -1);
+          write("\b \b");
+        }
+      } else if (char === "\x03") {
+        if (busy) {
+          agent.abort();
+          writeln("^C");
+          setStatus("Aborted");
+        } else if (input) {
+          redrawInput("");
+        } else {
+          writeln("^C");
+          writeln("Use /quit or close this browser tab to exit.");
+          writePrompt();
+        }
+      } else if (char === "\x1b") {
+        if (busy) agent.abort();
+      } else if (char >= " " && char !== "\x7f") {
+        input += char;
+        write(char);
+      }
+    }
+  }
+
+  nodes.confirmLoadModel.addEventListener("click", async () => {
+    device = nodes.gateDevice.value;
+    await loadModel();
+  });
+  nodes.useTestModel.addEventListener("click", () => {
+    mode = "mock";
+    modelReady = true;
+    resetAgent();
+    setModelStatus("Deterministic test model");
+    hideGate();
+    writeln("model: deterministic test model");
+    writePrompt();
+  });
+
+  resetAgent();
+  setStatus("Ready");
+  setSandboxStatus("Not booted");
+  setModelStatus(modelReady ? "Deterministic test model" : "Model idle");
+  nodes.gateDevice.value = device;
+  if (modelReady || params.get("setup") === "skip") hideGate();
+  else showGate("Ready.");
+
+  terminal.onData(handleData);
+  writeStartup();
+  writePrompt();
+
+  return {
+    loadModel,
+    handleLine,
+    get outputText() {
+      return outputText;
+    },
+    get transcript() {
+      return agent.state.messages
+        .map((message) => {
+          if (message.role === "toolResult") return `TOOL ${message.toolName}\n${textFromContent(message.content)}`;
+          return `${message.role.toUpperCase()}\n${textFromContent(message.content)}`;
+        })
+        .join("\n\n");
+    },
+    get modelReady() {
+      return modelReady;
+    },
+    get status() {
+      return status;
+    },
+    get mode() {
+      return mode;
+    },
+  };
+}

src/piCliContract.js

@@ -0,0 +1,101 @@
+export const PI_CLI_VERSION = "0.77.0";
+
+export const PI_DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
+export const PI_BUILTIN_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+export const PI_SLASH_COMMANDS = [
+  "/login",
+  "/logout",
+  "/model",
+  "/scoped-models",
+  "/settings",
+  "/resume",
+  "/new",
+  "/name <name>",
+  "/session",
+  "/tree",
+  "/fork",
+  "/clone",
+  "/compact [prompt]",
+  "/copy",
+  "/export [file]",
+  "/share",
+  "/reload",
+  "/hotkeys",
+  "/changelog",
+  "/quit",
+];
+
+export const PI_HELP_TEXT = `pi - AI coding assistant with read, bash, edit, write tools
+
+Usage:
+  pi [options] [@files...] [messages...]
+
+Commands:
+  pi install <source> [-l]     Install extension source and add to settings
+  pi remove <source> [-l]      Remove extension source from settings
+  pi uninstall <source> [-l]   Alias for remove
+  pi update [source|self|pi]   Update pi and installed extensions
+  pi list                      List installed extensions from settings
+  pi config                    Open TUI to enable/disable package resources
+  pi <command> --help          Show help for install/remove/uninstall/update/list
+
+Options:
+  --provider <name>              Provider name (default: google)
+  --model <pattern>              Model pattern or ID (supports "provider/id" and optional ":<thinking>")
+  --api-key <key>                API key (defaults to env vars)
+  --system-prompt <text>         System prompt (default: coding assistant prompt)
+  --append-system-prompt <text>  Append text or file contents to the system prompt (can be used multiple times)
+  --mode <mode>                  Output mode: text (default), json, or rpc
+  --print, -p                    Non-interactive mode: process prompt and exit
+  --continue, -c                 Continue previous session
+  --resume, -r                   Select a session to resume
+  --session <path|id>            Use specific session file or partial UUID
+  --session-id <id>              Use exact project session ID, creating it if missing
+  --fork <path|id>               Fork specific session file or partial UUID into a new session
+  --session-dir <dir>            Directory for session storage and lookup
+  --no-session                   Don't save session (ephemeral)
+  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling
+  --no-tools, -nt                Disable all tools by default (built-in and extension)
+  --no-builtin-tools, -nbt       Disable built-in tools by default but keep extension/custom tools enabled
+  --tools, -t <tools>            Comma-separated allowlist of tool names to enable
+  --exclude-tools, -xt <tools>   Comma-separated denylist of tool names to disable
+  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh
+  --extension, -e <path>         Load an extension file (can be used multiple times)
+  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)
+  --skill <path>                 Load a skill file or directory (can be used multiple times)
+  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)
+  --theme <path>                 Load a theme file or directory (can be used multiple times)
+  --no-themes                    Disable theme discovery and loading
+  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading
+  --export <file>                Export session file to HTML and exit
+  --list-models [search]         List available models (with optional fuzzy search)
+  --verbose                      Force verbose startup (overrides quietStartup setting)
+  --offline                      Disable startup network operations (same as PI_OFFLINE=1)
+  --help, -h                     Show this help
+  --version, -v                  Show version number
+
+Built-in Tool Names:
+  read   - Read file contents
+  bash   - Execute bash commands
+  edit   - Edit files with find/replace
+  write  - Write files (creates/overwrites)
+  grep   - Search file contents (read-only, off by default)
+  find   - Find files by glob pattern (read-only, off by default)
+  ls     - List directory contents (read-only, off by default)`;
+
+export function formatHotkeys() {
+  return `Common Pi keybindings
+
+Ctrl+C        Clear editor
+Ctrl+C twice  Quit
+Escape        Cancel or abort
+Escape twice  Open /tree
+Ctrl+L        Open /model
+Ctrl+P        Cycle scoped models forward
+Shift+Ctrl+P  Cycle scoped models backward
+Shift+Tab     Cycle thinking level
+Ctrl+O        Collapse or expand tool output
+Ctrl+T        Collapse or expand thinking blocks
+Shift+Enter   Multi-line input`;
+}

src/sandbox.js

@@ -0,0 +1,388 @@
+const BOOT_FILES = {
+  "package.json": {
+    file: {
+      contents: JSON.stringify(
+        {
+          type: "module",
+          scripts: {
+            demo: "node hello.js",
+          },
+          dependencies: {},
+          devDependencies: {},
+        },
+        null,
+        2,
+      ),
+    },
+  },
+  "README.md": {
+    file: {
+      contents:
+        "# Pi web sandbox\n\nThis filesystem and every spawned process run inside WebContainers in this browser tab.\n",
+    },
+  },
+  "hello.js": {
+    file: {
+      contents: 'console.log("hello from the browser sandbox");\nconsole.log(2 + 2);\n',
+    },
+  },
+};
+
+const MAX_OUTPUT_CHARS = 16000;
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_READ_LINES = 2000;
+const DEFAULT_RESULT_LIMIT = 200;
+
+function splitCommandLine(value) {
+  const parts = [];
+  let current = "";
+  let quote = "";
+  let escaping = false;
+  for (const char of String(value || "")) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = "";
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === "\"" || char === "'") {
+      quote = char;
+    } else if (/\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function globToRegExp(glob) {
+  const source = String(glob || "*")
+    .split("*")
+    .map(escapeRegExp)
+    .join(".*");
+  return new RegExp(`^${source}$`);
+}
+
+export function createSandbox({ onLog = () => {}, onStatus = () => {} } = {}) {
+  let instance = null;
+  let booting = null;
+  let root = "";
+
+  async function boot() {
+    if (instance) return instance;
+    if (booting) return booting;
+
+    booting = (async () => {
+      if (!globalThis.crossOriginIsolated) {
+        throw new Error("WebContainers need cross-origin isolation. Start this app through Vite or another server that sends COOP/COEP headers.");
+      }
+
+      onStatus("Booting WebContainer");
+      const { WebContainer } = await import("@webcontainer/api");
+      instance = await WebContainer.boot({
+        coep: "credentialless",
+        workdirName: "workspace",
+      });
+      root = instance.workdir;
+      await instance.mount(BOOT_FILES);
+      onLog(`sandbox booted at ${root}`);
+      onStatus("Sandbox ready");
+      return instance;
+    })();
+
+    try {
+      return await booting;
+    } finally {
+      booting = null;
+    }
+  }
+
+  function assertRelativePath(path, { allowDot = false } = {}) {
+    let value = String(path ?? (allowDot ? "." : "")).trim();
+    if (value === "" && allowDot) value = ".";
+    value = value.replace(/^\/+/, "").replace(/^workspace\/?/, "");
+    if (value === "." && allowDot) return ".";
+    if (!value || value.includes("\0")) throw new Error("Path is required.");
+    const segments = value.split("/").filter(Boolean);
+    if (segments.some((segment) => segment === "..")) {
+      throw new Error("Paths must stay inside the sandbox workspace.");
+    }
+    const normalized = segments.filter((segment) => segment !== ".").join("/");
+    if (!normalized && allowDot) return ".";
+    if (!normalized) throw new Error("Path is required.");
+    return normalized;
+  }
+
+  function toWorkspacePath(path, options) {
+    return assertRelativePath(path, options);
+  }
+
+  async function pathExists(path) {
+    const wc = await boot();
+    try {
+      await wc.fs.stat(toWorkspacePath(path, { allowDot: true }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function reset() {
+    const wc = await boot();
+    const entries = await wc.fs.readdir(".");
+    await Promise.all(
+      entries.map((entry) =>
+        wc.fs.rm(entry, {
+          force: true,
+          recursive: true,
+        }),
+      ),
+    );
+    await wc.mount(BOOT_FILES);
+    onLog("sandbox reset");
+    return "Sandbox reset to the starter project.";
+  }
+
+  async function walkFiles(start = ".") {
+    const wc = await boot();
+    const rootPath = toWorkspacePath(start, { allowDot: true });
+    const files = [];
+
+    async function walk(current) {
+      const entries = await wc.fs.readdir(current, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        const child = current === "." ? entry.name : `${current}/${entry.name}`;
+        if (entry.isDirectory()) {
+          await walk(child);
+        } else {
+          files.push(child);
+        }
+      }
+    }
+
+    const stat = await wc.fs.stat(rootPath);
+    if (stat.isDirectory()) {
+      await walk(rootPath);
+    } else {
+      files.push(rootPath);
+    }
+    return files;
+  }
+
+  async function ls(path = ".", limit = DEFAULT_RESULT_LIMIT) {
+    const wc = await boot();
+    const target = toWorkspacePath(path || ".", { allowDot: true });
+    const stat = await wc.fs.stat(target);
+    if (!stat.isDirectory()) return `file ${target}`;
+    const entries = await wc.fs.readdir(target, { withFileTypes: true });
+    const capped = entries.slice(0, Number(limit || DEFAULT_RESULT_LIMIT));
+    const lines = capped.map((entry) => `${entry.isDirectory() ? "dir " : "file"} ${entry.name}`);
+    if (entries.length > capped.length) {
+      lines.push(`[Showing ${capped.length} of ${entries.length} entries. Use a larger limit to continue.]`);
+    }
+    return lines.join("\n") || "(empty)";
+  }
+
+  async function readTextFile(path, { offset, limit } = {}) {
+    const wc = await boot();
+    const target = toWorkspacePath(path);
+    const text = await wc.fs.readFile(target, "utf-8");
+    const lines = text.split("\n");
+    const start = Math.max(0, Number(offset || 1) - 1);
+    if (start >= lines.length) throw new Error(`Offset ${offset} is beyond end of file (${lines.length} lines total)`);
+    const maxLines = Number(limit || DEFAULT_MAX_READ_LINES);
+    const selected = lines.slice(start, start + maxLines);
+    let output = selected.join("\n");
+    if (start + selected.length < lines.length) {
+      output += `\n\n[${lines.length - start - selected.length} more lines in file. Use offset=${start + selected.length + 1} to continue.]`;
+    }
+    return output;
+  }
+
+  async function writeFile(path, content) {
+    const wc = await boot();
+    const relative = assertRelativePath(path);
+    const parent = relative.split("/").slice(0, -1).join("/");
+    if (parent) {
+      await wc.fs.mkdir(parent, { recursive: true });
+    }
+    await wc.fs.writeFile(relative, String(content ?? ""));
+    onLog(`wrote ${relative}`);
+    return `Successfully wrote ${String(content ?? "").length} bytes to ${relative}`;
+  }
+
+  async function editFile(path, edits = []) {
+    const wc = await boot();
+    const target = toWorkspacePath(path);
+    if (!Array.isArray(edits) || edits.length === 0) {
+      throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
+    }
+    const original = await wc.fs.readFile(target, "utf-8");
+    const replacements = [];
+    for (const edit of edits) {
+      const oldText = String(edit?.oldText ?? "");
+      const newText = String(edit?.newText ?? "");
+      if (!oldText) throw new Error("Every edit.oldText must be non-empty.");
+      const first = original.indexOf(oldText);
+      if (first === -1) throw new Error(`Could not edit file: ${path}. oldText was not found.`);
+      if (original.indexOf(oldText, first + oldText.length) !== -1) {
+        throw new Error(`Could not edit file: ${path}. oldText must match exactly one location.`);
+      }
+      replacements.push({ start: first, end: first + oldText.length, newText });
+    }
+    replacements.sort((a, b) => b.start - a.start);
+    for (let index = 1; index < replacements.length; index += 1) {
+      if (replacements[index].end > replacements[index - 1].start) {
+        throw new Error("Edit tool input is invalid. edits must not overlap.");
+      }
+    }
+    let next = original;
+    for (const replacement of replacements) {
+      next = `${next.slice(0, replacement.start)}${replacement.newText}${next.slice(replacement.end)}`;
+    }
+    await wc.fs.writeFile(target, next);
+    onLog(`edited ${target}`);
+    return `Successfully replaced ${edits.length} block(s) in ${path}.`;
+  }
+
+  async function findFiles(pattern = "*", path = ".", limit = DEFAULT_RESULT_LIMIT) {
+    const start = toWorkspacePath(path || ".", { allowDot: true });
+    if (!(await pathExists(start))) throw new Error(`Path does not exist: ${path || "."}`);
+    const matcher = globToRegExp(pattern);
+    const files = await walkFiles(start);
+    const matches = files.filter((file) => matcher.test(file) || matcher.test(file.split("/").pop() || ""));
+    const capped = matches.slice(0, Number(limit || DEFAULT_RESULT_LIMIT));
+    if (matches.length > capped.length) capped.push(`[Showing ${capped.length} of ${matches.length} matches. Use a larger limit to continue.]`);
+    return capped.join("\n") || "(no matches)";
+  }
+
+  async function grepFiles({ pattern, path = ".", glob = "*", ignoreCase = false, literal = false, context = 0, limit = DEFAULT_RESULT_LIMIT }) {
+    if (!pattern) throw new Error("pattern is required.");
+    const flags = ignoreCase ? "i" : "";
+    const matcher = literal ? new RegExp(escapeRegExp(pattern), flags) : new RegExp(pattern, flags);
+    const globMatcher = globToRegExp(glob || "*");
+    const files = (await walkFiles(path || ".")).filter((file) => globMatcher.test(file) || globMatcher.test(file.split("/").pop() || ""));
+    const matches = [];
+    for (const file of files) {
+      let text = "";
+      try {
+        text = await readTextFile(file, { limit: DEFAULT_MAX_READ_LINES });
+      } catch {
+        continue;
+      }
+      const lines = text.split("\n");
+      for (let index = 0; index < lines.length; index += 1) {
+        if (!matcher.test(lines[index])) continue;
+        matcher.lastIndex = 0;
+        const before = Math.max(0, index - Number(context || 0));
+        const after = Math.min(lines.length - 1, index + Number(context || 0));
+        for (let lineIndex = before; lineIndex <= after; lineIndex += 1) {
+          matches.push(`${file}:${lineIndex + 1}:${lines[lineIndex]}`);
+          if (matches.length >= Number(limit || DEFAULT_RESULT_LIMIT)) {
+            matches.push(`[Showing first ${matches.length - 1} matches. Use a larger limit to continue.]`);
+            return matches.join("\n");
+          }
+        }
+      }
+    }
+    return matches.join("\n") || "(no matches)";
+  }
+
+  async function spawnProcess(command, args = [], timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const wc = await boot();
+    const cmd = String(command || "").trim();
+    if (!cmd) throw new Error("Command is required.");
+    const cleanArgs = Array.isArray(args) ? args.map((arg) => String(arg)) : [];
+
+    onLog(`$ ${[cmd, ...cleanArgs].join(" ")}`);
+    const process = await wc.spawn(cmd, cleanArgs, {
+      terminal: {
+        cols: 96,
+        rows: 28,
+      },
+    });
+
+    let output = "";
+    const reader = process.output.getReader();
+    const pump = (async () => {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        output += value;
+        if (output.length > MAX_OUTPUT_CHARS) {
+          output = `${output.slice(0, MAX_OUTPUT_CHARS)}\n[output truncated]`;
+          process.kill();
+          break;
+        }
+      }
+    })();
+
+    const timeout = new Promise((resolve) => {
+      setTimeout(() => {
+        process.kill();
+        resolve("timeout");
+      }, Number(timeoutMs) || DEFAULT_TIMEOUT_MS);
+    });
+
+    const exitCode = await Promise.race([process.exit, timeout]);
+    await pump.catch(() => {});
+    const normalizedExitCode = exitCode === "timeout" ? 124 : exitCode;
+    const result = {
+      command: [cmd, ...cleanArgs].join(" "),
+      exitCode: normalizedExitCode,
+      output: output.trimEnd(),
+    };
+    onLog(`exit ${normalizedExitCode}`);
+    return result;
+  }
+
+  async function bash(command, timeoutSeconds) {
+    const timeoutMs = timeoutSeconds ? Number(timeoutSeconds) * 1000 : DEFAULT_TIMEOUT_MS;
+    try {
+      return await spawnProcess("jsh", ["-c", command], timeoutMs);
+    } catch (error) {
+      const parts = splitCommandLine(command);
+      if (parts.length === 0) throw error;
+      return await spawnProcess(parts[0], parts.slice(1), timeoutMs);
+    }
+  }
+
+  return {
+    boot,
+    reset,
+    bash,
+    editFile,
+    findFiles,
+    grepFiles,
+    ls,
+    listFiles: ls,
+    readFile: (path) => readTextFile(path),
+    readTextFile,
+    writeFile,
+    runCommand: spawnProcess,
+    get isReady() {
+      return Boolean(instance);
+    },
+  };
+}

src/styles.css

@@ -0,0 +1,226 @@
+:root {
+  color: #d6deeb;
+  background: #0b0f16;
+  font-family:
+    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#app {
+  min-width: 320px;
+  min-height: 100vh;
+  margin: 0;
+}
+
+button,
+select {
+  font: inherit;
+}
+
+button {
+  min-height: 40px;
+  padding: 0 15px;
+  border: 0;
+  border-radius: 6px;
+  background: #227c70;
+  color: #ffffff;
+  font-weight: 750;
+  cursor: pointer;
+}
+
+button:disabled {
+  cursor: wait;
+  opacity: 0.6;
+}
+
+#app {
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
+  gap: 10px;
+  padding: 10px;
+}
+
+.runtime-bar {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: 16px;
+  min-height: 54px;
+  padding: 4px 2px 10px;
+  border-bottom: 1px solid #263244;
+}
+
+h1,
+h2,
+p {
+  margin: 0;
+}
+
+h1 {
+  color: #f8fafc;
+  font-size: 30px;
+  line-height: 1;
+  letter-spacing: 0;
+}
+
+#model-label {
+  margin-top: 5px;
+  color: #9eb1ca;
+  font-size: 13px;
+  overflow-wrap: anywhere;
+}
+
+.status-stack {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: end;
+  gap: 8px;
+  max-width: 760px;
+}
+
+.status {
+  min-height: 32px;
+  max-width: 280px;
+  padding: 6px 10px;
+  border: 1px solid #344156;
+  border-radius: 6px;
+  background: #141b27;
+  color: #cad7ea;
+  font-size: 13px;
+  overflow-wrap: anywhere;
+}
+
+.terminal-shell {
+  min-height: 0;
+  border: 1px solid #263244;
+  border-radius: 8px;
+  background: #10141c;
+  overflow: hidden;
+}
+
+#terminal {
+  width: 100%;
+  height: calc(100vh - 86px);
+  min-height: 420px;
+  padding: 10px;
+}
+
+.xterm {
+  height: 100%;
+}
+
+.xterm-viewport,
+.xterm-screen {
+  border-radius: 0;
+}
+
+.model-gate {
+  position: fixed;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 18px;
+  background: rgba(4, 8, 14, 0.64);
+  z-index: 20;
+}
+
+.model-gate.hidden {
+  display: none;
+}
+
+.model-dialog {
+  display: grid;
+  gap: 16px;
+  width: min(560px, 100%);
+  padding: 22px;
+  border: 1px solid #334155;
+  border-radius: 8px;
+  background: #f8fafc;
+  color: #172033;
+  box-shadow: 0 24px 80px rgba(0, 0, 0, 0.35);
+}
+
+.eyebrow {
+  margin-bottom: 7px;
+  color: #227c70;
+  font-size: 12px;
+  font-weight: 850;
+  text-transform: uppercase;
+}
+
+.model-dialog h2 {
+  color: #172033;
+  font-size: 24px;
+  line-height: 1.15;
+}
+
+.dialog-copy {
+  margin-top: 8px;
+  color: #526173;
+  line-height: 1.5;
+}
+
+.dialog-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+#use-test-model {
+  background: #4f5f73;
+}
+
+.dialog-options {
+  display: grid;
+  gap: 10px;
+  color: #526173;
+}
+
+label {
+  display: grid;
+  gap: 6px;
+  font-size: 13px;
+  font-weight: 700;
+}
+
+select {
+  width: 100%;
+  height: 40px;
+  padding: 0 10px;
+  border: 1px solid #b8c5d4;
+  border-radius: 6px;
+  background: #ffffff;
+  color: #152033;
+}
+
+#gate-status {
+  min-height: 22px;
+  color: #526173;
+  overflow-wrap: anywhere;
+}
+
+@media (max-width: 760px) {
+  #app {
+    padding: 8px;
+  }
+
+  .runtime-bar {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .status-stack {
+    justify-content: start;
+  }
+
+  #terminal {
+    height: calc(100vh - 164px);
+    min-height: 360px;
+    padding: 8px;
+  }
+}

src/webTerminal.js

@@ -0,0 +1,97 @@
+import "@xterm/xterm/css/xterm.css";
+
+const THEME = {
+  background: "#10141c",
+  foreground: "#d6deeb",
+  cursor: "#f7c948",
+  cursorAccent: "#10141c",
+  selectionBackground: "#334155",
+  black: "#111827",
+  red: "#f87171",
+  green: "#34d399",
+  yellow: "#facc15",
+  blue: "#60a5fa",
+  magenta: "#c084fc",
+  cyan: "#22d3ee",
+  white: "#f8fafc",
+  brightBlack: "#475569",
+  brightRed: "#fca5a5",
+  brightGreen: "#86efac",
+  brightYellow: "#fde68a",
+  brightBlue: "#93c5fd",
+  brightMagenta: "#d8b4fe",
+  brightCyan: "#67e8f9",
+  brightWhite: "#ffffff",
+};
+
+function normalizeNewlines(text) {
+  return String(text).replace(/\r?\n/g, "\r\n");
+}
+
+function withTimeout(promise, ms, label) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    }),
+  ]);
+}
+
+export async function createWebTerminal(container) {
+  let terminal;
+  let fitAddon;
+  let engine = "ghostty-web";
+
+  try {
+    const ghostty = await withTimeout(import("ghostty-web"), 3000, "ghostty-web import");
+    await withTimeout(ghostty.init(), 3000, "ghostty-web init");
+    terminal = new ghostty.Terminal({
+      cursorBlink: true,
+      fontFamily: "JetBrains Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace",
+      fontSize: 14,
+      rows: 30,
+      cols: 100,
+      scrollback: 5000,
+      theme: THEME,
+    });
+    fitAddon = new ghostty.FitAddon();
+    terminal.loadAddon(fitAddon);
+  } catch (error) {
+    const [{ Terminal }, { FitAddon }] = await Promise.all([import("@xterm/xterm"), import("@xterm/addon-fit")]);
+    engine = "xterm";
+    terminal = new Terminal({
+      cursorBlink: true,
+      fontFamily: "JetBrains Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace",
+      fontSize: 14,
+      rows: 30,
+      cols: 100,
+      scrollback: 5000,
+      theme: THEME,
+    });
+    fitAddon = new FitAddon();
+    terminal.loadAddon(fitAddon);
+    console.warn("ghostty-web failed, using xterm fallback", error);
+  }
+
+  terminal.open(container);
+  fitAddon.fit();
+  terminal.focus();
+
+  const resizeObserver = new ResizeObserver(() => fitAddon.fit());
+  resizeObserver.observe(container);
+
+  return {
+    engine,
+    raw: terminal,
+    onData: (handler) => terminal.onData(handler),
+    write: (text) => terminal.write(normalizeNewlines(text)),
+    writeln: (text = "") => terminal.write(`${normalizeNewlines(text)}\r\n`),
+    clear: () => terminal.clear(),
+    focus: () => terminal.focus(),
+    fit: () => fitAddon.fit(),
+    dispose: () => {
+      resizeObserver.disconnect();
+      terminal.dispose();
+    },
+  };
+}

vite.config.js

@@ -0,0 +1,16 @@
+import { defineConfig } from "vite";
+
+const headers = {
+  "Cross-Origin-Embedder-Policy": "credentialless",
+  "Cross-Origin-Opener-Policy": "same-origin",
+};
+
+export default defineConfig({
+  server: {
+    headers,
+  },
+  preview: {
+    headers,
+  },
+});
+