march-cli 0.1.34 → 0.1.36

package/src/provider/quota/transport-observer.mjs

@@ -0,0 +1,99 @@
+const FETCH_INSTALLED = Symbol.for("march.providerQuota.fetchObserverInstalled");
+const WEBSOCKET_INSTALLED = Symbol.for("march.providerQuota.websocketObserverInstalled");
+const LISTENERS = Symbol.for("march.providerQuota.transportListeners");
+
+export function installProviderQuotaTransportObserver() {
+  installFetchObserver();
+  installWebSocketObserver();
+}
+
+export function subscribeProviderQuotaTransport(listener) {
+  const listeners = ensureListeners();
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function installFetchObserver() {
+  if (globalThis[FETCH_INSTALLED]) return;
+  const originalFetch = globalThis.fetch;
+  if (typeof originalFetch !== "function") return;
+  globalThis.fetch = async function marchProviderQuotaFetch(input, init = {}) {
+    const response = await originalFetch.call(this, input, init);
+    if (isCodexResponsesHttpRequest(input, init)) {
+      notifyTransportListeners({ providerId: "openai-codex", source: "headers", headers: response.headers });
+    }
+    return response;
+  };
+  globalThis[FETCH_INSTALLED] = true;
+}
+
+function installWebSocketObserver() {
+  if (globalThis[WEBSOCKET_INSTALLED]) return;
+  const OriginalWebSocket = globalThis.WebSocket;
+  if (typeof OriginalWebSocket !== "function") return;
+
+  class MarchProviderQuotaWebSocket extends OriginalWebSocket {
+    constructor(url, protocolsOrOptions, maybeOptions) {
+      if (!isCodexResponsesWebSocketUrl(url)) {
+        return new OriginalWebSocket(url, protocolsOrOptions, maybeOptions);
+      }
+      super(url, protocolsOrOptions, maybeOptions);
+      this.addEventListener?.("message", async (event) => {
+        const payload = await decodeWebSocketData(event?.data).catch(() => null);
+        if (payload?.includes?.('"codex.rate_limits"')) {
+          notifyTransportListeners({ providerId: "openai-codex", source: "event", payload });
+        }
+      });
+    }
+  }
+  copyReadyStateConstants(MarchProviderQuotaWebSocket, OriginalWebSocket);
+  globalThis.WebSocket = MarchProviderQuotaWebSocket;
+  globalThis[WEBSOCKET_INSTALLED] = true;
+}
+
+function ensureListeners() {
+  globalThis[LISTENERS] = globalThis[LISTENERS] ?? new Set();
+  return globalThis[LISTENERS];
+}
+
+function notifyTransportListeners(event) {
+  for (const listener of [...ensureListeners()]) {
+    try {
+      listener(event);
+    } catch {}
+  }
+}
+
+function isCodexResponsesHttpRequest(input, init) {
+  const url = getRequestUrl(input);
+  if (!url || !url.includes("/codex/responses")) return false;
+  const method = init?.method ?? input?.method ?? "GET";
+  return String(method).toUpperCase() === "POST";
+}
+
+function isCodexResponsesWebSocketUrl(url) {
+  const raw = getRequestUrl(url);
+  return Boolean(raw?.includes("/codex/responses") && (raw.startsWith("ws://") || raw.startsWith("wss://")));
+}
+
+function getRequestUrl(input) {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  if (input && typeof input.url === "string") return input.url;
+  return "";
+}
+
+async function decodeWebSocketData(data) {
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(new Uint8Array(data));
+  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+  if (data && typeof data.arrayBuffer === "function") return new TextDecoder().decode(new Uint8Array(await data.arrayBuffer()));
+  return null;
+}
+
+function copyReadyStateConstants(Target, OriginalWebSocket) {
+  for (const key of ["CONNECTING", "OPEN", "CLOSING", "CLOSED"]) {
+    const value = OriginalWebSocket[key];
+    if (typeof value === "number") Object.defineProperty(Target, key, { value, enumerable: true });
+  }
+}

package/src/web-ui/command.mjs

@@ -0,0 +1,112 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createWebUiServer } from "./server.mjs";
+import { createWebSessionManager, resolveWorkspace } from "./session-manager.mjs";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 4174;
+
+export async function runWebUiCommand(args, { config, cwd, stateRoot, useRuntimeProcess = true } = {}) {
+  const host = args.host ?? DEFAULT_HOST;
+  assertLoopbackHost(host);
+  const port = Number.parseInt(args.port ?? "", 10) || DEFAULT_PORT;
+  const runtime = createWebSessionManager({ args, config, launchCwd: cwd, stateRoot, useRuntimeProcess });
+  const initialWorkspace = resolveInitialWorkspace(args, cwd);
+  if (initialWorkspace) await runtime.createSession(initialWorkspace);
+
+  if (args.dev) return runWebUiDevCommand({ args, host, port, runtime, initialWorkspace });
+  assertWebBuildReady();
+  const server = createWebUiServer({ runtime });
+  await listen(server, port, host);
+  process.stdout.write(`March Web running at http://${host}:${port}\n`);
+  if (initialWorkspace) process.stdout.write(`Workspace: ${initialWorkspace}\n`);
+  await waitForShutdown({ servers: [server], runtime });
+  return 0;
+}
+
+export function resolveInitialWorkspace(args, launchCwd) {
+  const positional = args.command?.args ?? [];
+  if (positional.length > 1) throw new Error("Usage: march web [workspace] [--host <host>] [--port <port>]");
+  if (args.workspace && positional.length > 0) throw new Error("Use either march web <workspace> or --workspace <path>, not both");
+  const requested = args.workspace ?? positional[0];
+  return requested ? resolveWorkspace(requested, launchCwd) : null;
+}
+
+function assertLoopbackHost(host) {
+  if (["127.0.0.1", "localhost", "::1"].includes(host)) return;
+  throw new Error("march web only exposes local filesystem APIs on 127.0.0.1/localhost");
+}
+
+function assertWebBuildReady() {
+  if (existsSync(new URL("./dist/index.html", import.meta.url))) return;
+  throw new Error("Web UI build not found. Run: npm run web:build or use march web --dev");
+}
+
+async function runWebUiDevCommand({ args, host, port, runtime, initialWorkspace }) {
+  const apiPort = Number.parseInt(args.apiPort ?? "", 10) || port + 1;
+  const apiServer = createWebUiServer({ runtime });
+  let apiStarted = false;
+  try {
+    await listen(apiServer, apiPort, host);
+    apiStarted = true;
+    const vite = await createViteDevServer({ host, port, apiPort });
+    process.stdout.write(`March Web dev running at http://${host}:${port}\n`);
+    process.stdout.write(`March Web API running at http://${host}:${apiPort}\n`);
+    if (initialWorkspace) process.stdout.write(`Workspace: ${initialWorkspace}\n`);
+    await waitForShutdown({ servers: [apiServer], runtime, vite });
+    return 0;
+  } catch (err) {
+    if (apiStarted) await closeServer(apiServer);
+    await runtime.dispose?.();
+    throw err;
+  }
+}
+
+async function createViteDevServer({ host, port, apiPort }) {
+  let createServer;
+  try {
+    ({ createServer } = await import("vite"));
+  } catch {
+    throw new Error("Vite is required for march web --dev. Run npm install in the March repo.");
+  }
+  const vite = await createServer({
+    configFile: fileURLToPath(new URL("./vite.config.mjs", import.meta.url)),
+    server: {
+      host,
+      port,
+      strictPort: true,
+      proxy: { "/api": `http://${host}:${apiPort}` },
+    },
+  });
+  await vite.listen();
+  return vite;
+}
+
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => server.close(resolve));
+}
+
+function waitForShutdown({ servers, runtime, vite = null }) {
+  return new Promise((resolve) => {
+    const shutdown = async () => {
+      process.off("SIGINT", shutdown);
+      process.off("SIGTERM", shutdown);
+      if (vite) await vite.close();
+      await Promise.all(servers.map(closeServer));
+      await runtime.dispose?.();
+      resolve();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}

package/src/web-ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>March Web</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/src/web-ui/runtime-host.mjs

@@ -0,0 +1,188 @@
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { createMarchAuthStorage } from "../auth/storage.mjs";
+import { createRuntimeRunner } from "../cli/startup/create-runtime-runner.mjs";
+import { createPermissionController, MODE } from "../cli/permissions.mjs";
+import { createCliShellRuntime } from "../shell/cli-runtime.mjs";
+import { MarkdownMemoryStore } from "../memory/markdown-store.mjs";
+import { createMarkdownMemoryTools } from "../memory/markdown-tools.mjs";
+import { resolveMemoryRoot } from "../memory/root.mjs";
+import { defaultProfilePaths, ensureProfileFiles } from "../context/profiles.mjs";
+import { loadOrCreateProjectId } from "../cli/startup/startup-session.mjs";
+import { createWebToolsFromConfig } from "../web/tools.mjs";
+import { createLogger, installProcessLogHandlers } from "../debug/logger.mjs";
+import { createModelContextDumper } from "../debug/model-context-dumper.mjs";
+import { createDesktopTurnNotifier } from "../notification/desktop-notifier.mjs";
+import { discoverProjectExtensionPaths } from "../extensions/discovery.mjs";
+import { loadProjectLifecycleHookManifests } from "../extensions/lifecycle-manifest.mjs";
+import { normalizeRemoteMemorySources } from "../memory/remote/config.mjs";
+import { prepareTurnInput } from "../cli/turn/turn-input-preparer.mjs";
+
+const MAX_WORKSPACE_DEPTH = 3;
+const MAX_WORKSPACE_ENTRIES = 200;
+
+export async function createWebRuntimeHost({ args, config, cwd, stateRoot, useRuntimeProcess = true } = {}) {
+  stateRoot ??= join(homedir(), ".march");
+  if (!existsSync(stateRoot)) mkdirSync(stateRoot, { recursive: true });
+  const logger = createLogger({ logDir: join(stateRoot, "logs") });
+  installProcessLogHandlers(logger);
+  const provider = args.provider ?? config.provider ?? null;
+  const model = args.model ?? config.model ?? null;
+  const authConfig = createMarchAuthStorage({ provider: provider ?? "deepseek", providers: config.providers, cwd });
+  if (!authConfig.hasAuth) throw new Error("No providers configured. Run: march provider --config");
+
+  const projectMarchDir = resolve(cwd, ".march");
+  if (!existsSync(projectMarchDir)) mkdirSync(projectMarchDir, { recursive: true });
+  const memoryRoot = resolveMemoryRoot(config.memoryRoot, stateRoot);
+  const profilePaths = defaultProfilePaths();
+  ensureProfileFiles(profilePaths);
+
+  const memoryStore = new MarkdownMemoryStore({ root: memoryRoot });
+  const remoteMemorySources = normalizeRemoteMemorySources(config);
+  const memoryTools = createMarkdownMemoryTools(memoryStore, { remoteSources: remoteMemorySources });
+  const shellRuntime = args.shellRuntime ? createCliShellRuntime({ cwd }) : null;
+  const extensionPaths = discoverProjectExtensionPaths(cwd);
+  const lifecycleManifests = loadProjectLifecycleHookManifests(cwd);
+  const contextDumpRoot = resolve(projectMarchDir, "context-dumps", Date.now().toString(36));
+  const modelContextDumper = createModelContextDumper({ enabled: args.dumpContext, rootDir: contextDumpRoot });
+  const permissionController = createPermissionController({ mode: args.permissionMode ?? MODE.BYPASS });
+  const turnNotifier = createDesktopTurnNotifier({ enabled: Boolean(config.notifications?.turnEnd), config: config.notifications });
+  const ui = createHeadlessWebUi();
+  const currentProject = basename(cwd);
+  const namespace = loadOrCreateProjectId(projectMarchDir);
+  const runnerOptions = {
+    cwd,
+    modelId: model,
+    provider,
+    serviceTier: config.serviceTier ?? null,
+    providers: config.providers,
+    config,
+    stateRoot,
+    memoryRoot,
+    profilePaths,
+    namespace,
+    projectMarchDir,
+    extensionPaths,
+    permissionMode: args.permissionMode,
+    shellRuntime: Boolean(shellRuntime),
+    lifecycleHooks: lifecycleManifests.hooks,
+    lifecycleDiagnostics: lifecycleManifests.diagnostics,
+    modelContextDumper: { enabled: args.dumpContext, rootDir: contextDumpRoot },
+    remoteMemorySources,
+  };
+  const runner = await createRuntimeRunner({
+    useRuntimeProcess,
+    runnerOptions,
+    ui,
+    memoryStore,
+    memoryTools,
+    shellRuntime,
+    webTools: createWebToolsFromConfig(config),
+    usePiSessions: true,
+    usePiRuntimeHost: true,
+    authStorage: authConfig.authStorage,
+    permissionController,
+    modelContextDumper,
+    turnNotifier,
+    logger,
+  });
+  let turnRunning = false;
+
+  return {
+    runner,
+    memoryStore,
+    logger,
+    currentProject,
+    snapshot: () => createWebSnapshot({ cwd, runner, currentProject }),
+    subscribe: (listener) => runner.runtimeUiEvents.on(listener),
+    refreshProviderQuota: () => runner.getProviderQuotaSnapshot?.({ emit: true }) ?? null,
+    async runTurn(prompt) {
+      if (turnRunning) throw new Error("A turn is already running");
+      turnRunning = true;
+      const input = prepareTurnInput({ prompt, runner, memoryStore, currentProject });
+      runner.runtimeUiEvents.emit({ type: "web_user_message", text: input.userMessage });
+      try {
+        return await runner.runTurn(input.fullPrompt, input.userMessage, input.runOptions);
+      } finally {
+        turnRunning = false;
+        memoryStore.endTurn();
+      }
+    },
+    abort: () => runner.abort(),
+    async dispose() {
+      await runner.dispose?.();
+      memoryStore.close?.();
+    },
+  };
+}
+
+export function createHeadlessWebUi() {
+  return {
+    readline: () => Promise.resolve(null), write: () => {}, writeln: () => {},
+    thinkingStart: () => {}, thinkingDelta: () => {}, thinkingEnd: () => {},
+    thinkingBlock: () => {}, toggleLastThinking: () => false,
+    toolStart: () => {}, toolEnd: () => {}, textDelta: () => {},
+    assistantReplyEnd: () => {}, status: () => {}, recall: () => {},
+    providerQuotaSnapshot: () => {},
+    clearOutput: () => {}, restoreTranscript: () => {}, setStatusBar: () => {},
+    turnStart: () => {}, turnEnd: () => {}, retryStart: () => {}, retryEnd: () => {},
+    editDiff: () => {}, requestPermission: async () => true,
+    setEscapeHandler: () => {}, setCtrlCHandler: () => {}, setShiftTabHandler: () => {},
+    setCtrlTHandler: () => {}, setCtrlLHandler: () => {}, setPasteImageHandler: () => {},
+    getInputText: () => "", insertTextAtCursor: () => {}, openExternalEditor: () => {},
+    toggleToolOutput: () => false, requestExit: () => {}, close: () => {},
+  };
+}
+
+export function createWebSnapshot({ cwd, runner, currentProject = basename(cwd) }) {
+  const model = runner.getCurrentModel?.();
+  return {
+    workspace: readWorkspaceTree(cwd),
+    timeline: { title: currentProject, meta: runtimeMeta(model), events: [] },
+    providerQuota: runner.getCachedProviderQuotaSnapshot?.() ?? null,
+    sessions: [{ id: "current", title: runner.engine?.sessionName ?? currentProject, time: "now", active: true }],
+    activity: [{ id: "runtime", action: "runner connected", time: "now" }],
+    composer: { mode: "Chat", placeholder: "Message March…" },
+  };
+}
+
+function runtimeMeta(model) {
+  return [model?.provider, model?.id].filter(Boolean).join(" · ") || "runner connected";
+}
+
+function readWorkspaceTree(rootPath) {
+  let count = 0;
+  const rootName = basename(rootPath) || rootPath;
+  return readNode(rootPath, rootName, 0, true);
+
+  function readNode(path, name, depth, selected = false) {
+    const stat = safeStat(path);
+    const kind = stat?.isDirectory() ? "folder" : "file";
+    const node = { id: path, name, kind, selected };
+    if (kind !== "folder" || depth >= MAX_WORKSPACE_DEPTH || count >= MAX_WORKSPACE_ENTRIES) return node;
+    const children = safeReadDir(path)
+      .filter((entry) => !entry.name.startsWith(".git") && entry.name !== "node_modules")
+      .sort(compareEntries)
+      .slice(0, 80)
+      .map((entry) => {
+        count += 1;
+        return readNode(join(path, entry.name), entry.name, depth + 1);
+      });
+    if (children.length > 0) node.children = children;
+    return node;
+  }
+}
+
+function safeStat(path) {
+  try { return statSync(path); } catch { return null; }
+}
+
+function safeReadDir(path) {
+  try { return readdirSync(path, { withFileTypes: true }); } catch { return []; }
+}
+
+function compareEntries(a, b) {
+  if (a.isDirectory() !== b.isDirectory()) return a.isDirectory() ? -1 : 1;
+  return a.name.localeCompare(b.name);
+}

package/src/web-ui/server.mjs

@@ -0,0 +1,140 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, normalize, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const STATIC_ROOT = fileURLToPath(new URL("./dist/", import.meta.url));
+const DEFAULT_PORT = 4174;
+
+const rootPrefix = (root) => `${normalize(root).replace(/[\\/]$/, "")}${sep}`;
+
+const mimeTypes = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+]);
+
+export function createWebUiServer({ root = STATIC_ROOT, runtime = null } = {}) {
+  return createServer(async (req, res) => {
+    if (runtime && req.url?.startsWith("/api/")) {
+      await handleApiRequest(req, res, runtime);
+      return;
+    }
+    serveStaticRequest(req, res, root);
+  });
+}
+
+export async function handleApiRequest(req, res, runtime) {
+  const { pathname } = new URL(req.url ?? "/", "http://localhost");
+  try {
+    if (req.method === "GET" && pathname === "/api/snapshot") return sendJson(res, runtime.snapshot(getSessionId(req)));
+    if (req.method === "GET" && pathname === "/api/events") return streamRuntimeEvents(req, res, runtime);
+    if (req.method === "GET" && pathname === "/api/sessions") return sendJson(res, { sessions: runtime.listSessions() });
+    if (req.method === "POST" && pathname === "/api/sessions") return sendJson(res, await createRuntimeSession(req, runtime));
+    if (req.method === "GET" && pathname === "/api/fs/roots") return sendJson(res, { roots: runtime.fsRoots() });
+    if (req.method === "GET" && pathname === "/api/fs/list") return sendJson(res, { entries: runtime.fsList(getPathParam(req)) });
+    if (req.method === "GET" && pathname === "/api/provider-quota") return sendJson(res, { snapshot: await runtime.refreshProviderQuota(getSessionId(req)) });
+    if (req.method === "POST" && pathname === "/api/turn") return sendJson(res, await runRuntimeTurn(req, runtime));
+    if (req.method === "POST" && pathname === "/api/abort") return sendJson(res, { ok: true, result: runtime.abort(getSessionId(req)) });
+    sendJson(res, { error: "Not found" }, 404);
+  } catch (err) {
+    sendJson(res, { error: err?.message ?? String(err) }, 500);
+  }
+}
+
+export function resolveStaticPath(root, requestUrl) {
+  const url = new URL(requestUrl, "http://localhost");
+  const pathname = url.pathname === "/" ? "/index.html" : url.pathname;
+  const decoded = decodeURIComponent(pathname);
+  const candidate = normalize(join(root, decoded));
+  return candidate.startsWith(rootPrefix(root)) ? candidate : null;
+}
+
+function serveStaticRequest(req, res, root) {
+  const filePath = resolveStaticPath(root, req.url ?? "/");
+  if (!filePath) {
+    res.writeHead(403);
+    res.end("Forbidden");
+    return;
+  }
+
+  if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+    res.writeHead(404);
+    res.end("Not found");
+    return;
+  }
+
+  const type = mimeTypes.get(extname(filePath)) ?? "application/octet-stream";
+  res.writeHead(200, { "content-type": type });
+  createReadStream(filePath).pipe(res);
+}
+
+async function createRuntimeSession(req, runtime) {
+  const body = await readJsonBody(req);
+  const session = await runtime.createSession(body.workspacePath);
+  return { ok: true, session, snapshot: runtime.snapshot(session.id) };
+}
+
+async function runRuntimeTurn(req, runtime) {
+  const body = await readJsonBody(req);
+  const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+  if (!prompt) throw new Error("Missing prompt");
+  const result = await runtime.runTurn(body.sessionId, prompt);
+  return { ok: true, draft: result?.draft ?? "" };
+}
+
+function streamRuntimeEvents(req, res, runtime) {
+  res.writeHead(200, {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-cache, no-transform",
+    connection: "keep-alive",
+  });
+  writeSse(res, "ready", { ok: true });
+  const unsubscribe = runtime.subscribe(getSessionId(req), (event) => writeSse(res, "runtime", event));
+  res.on("close", unsubscribe);
+}
+
+function getSessionId(req) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  return url.searchParams.get("sessionId");
+}
+
+function getPathParam(req) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const path = url.searchParams.get("path");
+  if (!path) throw new Error("Missing path");
+  return path;
+}
+
+function writeSse(res, event, data) {
+  res.write(`event: ${event}\n`);
+  res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+
+function sendJson(res, data, status = 200) {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(data));
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > 1_000_000) reject(new Error("Request body too large"));
+    });
+    req.on("end", () => {
+      try { resolve(raw ? JSON.parse(raw) : {}); } catch { reject(new Error("Invalid JSON body")); }
+    });
+    req.on("error", reject);
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const port = Number.parseInt(process.env.MARCH_WEB_PORT ?? "", 10) || DEFAULT_PORT;
+  createWebUiServer().listen(port, "127.0.0.1", () => {
+    console.log(`March Web preview running at http://127.0.0.1:${port}`);
+  });
+}

package/src/web-ui/session-manager.mjs

@@ -0,0 +1,111 @@
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, resolve } from "node:path";
+import { createWebRuntimeHost } from "./runtime-host.mjs";
+
+export function createWebSessionManager({ args, config, launchCwd, stateRoot, useRuntimeProcess = true } = {}) {
+  const sessions = new Map();
+  const activities = [];
+  let activeSessionId = null;
+  let nextSessionNumber = 1;
+
+  async function createSession(workspacePath) {
+    const workspace = resolveWorkspace(workspacePath, launchCwd);
+    const id = `session-${Date.now().toString(36)}-${nextSessionNumber++}`;
+    const runtime = await createWebRuntimeHost({ args, config, cwd: workspace, stateRoot, useRuntimeProcess });
+    const session = { id, workspace, title: basename(workspace) || workspace, runtime, createdAt: Date.now() };
+    sessions.set(id, session);
+    activeSessionId = id;
+    activities.unshift({ id: `activity:${id}`, action: `opened ${session.title}`, time: "now" });
+    return toSessionSummary(session, true);
+  }
+
+  const listSessions = () => Array.from(sessions.values()).map((session) => toSessionSummary(session, session.id === activeSessionId));
+
+  return {
+    async createSession(workspacePath) { return createSession(workspacePath); },
+    listSessions,
+    snapshot(sessionId = activeSessionId) {
+      const session = getOptionalSession(sessions, sessionId);
+      if (!session) return createEmptySnapshot({ sessions, activeSessionId, activities });
+      const model = session.runtime.snapshot();
+      return { ...model, sessions: listSessions(), activity: activities, activeSessionId: session.id };
+    },
+    subscribe(sessionId, listener) { return getSession(sessions, sessionId).runtime.subscribe(listener); },
+    runTurn(sessionId, prompt) { return getSession(sessions, sessionId).runtime.runTurn(prompt); },
+    refreshProviderQuota(sessionId) { return getSession(sessions, sessionId).runtime.refreshProviderQuota?.() ?? null; },
+    abort(sessionId) { return getSession(sessions, sessionId).runtime.abort?.(); },
+    fsRoots() { return listFsRoots(launchCwd); },
+    fsList(path) { return listFsDirectory(path); },
+    async dispose() {
+      await Promise.all(Array.from(sessions.values()).map((session) => session.runtime.dispose?.()));
+      sessions.clear();
+    },
+  };
+}
+
+export function resolveWorkspace(requested, launchCwd = process.cwd()) {
+  if (!requested || typeof requested !== "string") throw new Error("Missing workspace path");
+  const workspace = resolve(launchCwd, requested);
+  if (!isDirectory(workspace)) throw new Error(`Workspace does not exist or is not a directory: ${workspace}`);
+  return workspace;
+}
+
+function getSession(sessions, id) {
+  const session = getOptionalSession(sessions, id);
+  if (!session) throw new Error("Session not found");
+  return session;
+}
+
+function getOptionalSession(sessions, id) {
+  if (!id) return null;
+  return sessions.get(id) ?? null;
+}
+
+function toSessionSummary(session, active) {
+  return { id: session.id, title: session.title, workspacePath: session.workspace, time: "now", active };
+}
+
+function createEmptySnapshot({ sessions, activeSessionId, activities }) {
+  return {
+    workspace: { id: "no-workspace", name: "Choose workspace", kind: "folder", selected: true },
+    timeline: { title: "No session selected", meta: "Create a session and bind a workspace", events: [] },
+    sessions: Array.from(sessions.values()).map((session) => toSessionSummary(session, session.id === activeSessionId)),
+    providerQuota: null,
+    activity: activities,
+    activeSessionId: null,
+    composer: { mode: "No session", placeholder: "Choose a workspace to start…" },
+  };
+}
+
+function listFsRoots(launchCwd) {
+  const roots = uniquePaths([launchCwd, homedir(), ...windowsDriveRoots()]);
+  return roots.filter(isDirectory).map((path) => ({ name: path, path, kind: "root" }));
+}
+
+function windowsDriveRoots() {
+  if (process.platform !== "win32") return ["/"];
+  return Array.from({ length: 26 }, (_, index) => `${String.fromCharCode(65 + index)}:\\`);
+}
+
+function listFsDirectory(path) {
+  const root = resolve(path);
+  if (!isDirectory(root)) throw new Error(`Directory does not exist: ${root}`);
+  return safeReadDir(root)
+    .filter((entry) => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .slice(0, 500)
+    .map((entry) => ({ name: entry.name, path: resolve(root, entry.name), kind: "directory" }));
+}
+
+function uniquePaths(paths) {
+  return Array.from(new Set(paths.filter(Boolean).map((path) => resolve(path))));
+}
+
+function isDirectory(path) {
+  try { return statSync(path).isDirectory(); } catch { return false; }
+}
+
+function safeReadDir(path) {
+  try { return readdirSync(path, { withFileTypes: true }); } catch { return []; }
+}

package/src/web-ui/src/App.tsx

@@ -0,0 +1,7 @@
+import { AppShell } from "./components/AppShell";
+import { useWebRuntime } from "./runtime/useWebRuntime";
+
+export function App() {
+  const runtime = useWebRuntime();
+  return <AppShell runtime={runtime} />;
+}