pi-tau-web-server 1.0.8

package/README.md

@@ -0,0 +1,303 @@
+# Pi Tau Web Server
+
+**Browser workspace for [Pi](https://github.com/earendil-works/pi) — a standalone web server that manages multiple live Pi RPC sessions in parallel.**
+
+Pi Tau Web Server is a fork of [deflating/tau](https://github.com/deflating/tau), forked at
+[`5e2bce39`](https://github.com/deflating/tau/tree/5e2bce39) and rewritten from
+a Pi extension that ran inside the Pi TUI into a standalone Node.js web server.
+Instead of living inside a TUI session, Tau runs one backend process and spawns
+headless `pi --mode rpc` child processes — one per in-page Tau tab — so you can
+work with multiple Pi sessions side by side in your browser.
+
+## Key differences from `5e2bce39`
+
+| Area                  | Upstream (`5e2bce39`)                                                                         | This fork                                                                                                      |
+| --------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Architecture**      | Pi extension loaded inside the Pi TUI process; browser displayed a single running TUI session | Standalone Node.js server that spawns independent `pi --mode rpc` child processes                              |
+| **Multiple sessions** | Not supported                                                                                 | In-page tabs each backed by their own Pi RPC subprocess; run N sessions in parallel                            |
+| **Session lifecycle** | Tied to the Pi TUI session — close the TUI and the browser view died                          | Sessions are server-owned; closing/reloading the browser does not kill Pi children                             |
+| **Pi communication**  | In-process Pi extension API                                                                   | Out-of-process JSON line-delimited RPC over stdin/stdout                                                       |
+| **UI dialogs**        | `ctx.ui.confirm/input/select` shown in TUI only; not forwarded to the browser                 | All forwarded to the browser — extensions that use these built-in UI interfaces work seamlessly in the browser |
+| **Test coverage**     | Javascript and No tests                                                                       | Typescript + Full test suite                                                                                   |
+| **Auto-start**        | Extension auto-started inside Pi unless `TAU_DISABLED=1`                                      | Always explicit — the user runs `pi-tau-web-server` when they want it                                          |
+
+### Enhancements in this branch compared with `main`
+
+This branch also includes various enhancements over `main`, including a session-tree and branching interface that mirrors Pi TUI's `/tree` command. Open **Session tree** from the header or command palette to inspect every branch and continue from any earlier point; selecting a user message restores it to the composer so it can be edited and submitted as a new branch.
+
+![Tau light mode](docs/images/main-page.jpg)
+
+![Tau dark mode](docs/images/main-page-dark.jpg)
+
+![New tab modal](docs/images/new-tab.jpg)
+
+![Commands](docs/images/commands.png)
+
+![Model completion](docs/images/model-completion.jpg)
+
+![Settings](docs/images/settings.png)
+
+![Mobile main page](docs/images/mobile-main-page.jpeg)
+
+![Mobile sidebar](docs/images/mobile-side-bar.jpeg)
+
+## What it does
+
+- **Standalone server** — run `pi-tau-web-server`; it serves the web UI and manages Pi RPC child processes as subprocesses via `pi --mode rpc`
+- **Multiple live sessions** — in-page Tau tabs (not browser tabs) each represent a live Pi RPC session. Create, switch, and close them from one browser page. Tau runs all of them in parallel.
+- **Session persistence while the server runs** — closing or reloading the browser does not kill Pi child sessions; only closing an in-page Tau tab or shutting down the Tau server does
+- **Works on any device** — open the same Tau server from your phone, tablet, or another monitor
+- **Session history browser** — view saved Pi JSONL session files, search across all sessions by message content
+- **WebSocket-based client-server architecture** — the browser connects to Tau over HTTP and WebSocket; Tau communicates with Pi processes over JSON line-delimited RPC over stdin/stdout
+
+## Install
+
+Requires Node.js 22.19 or newer and [Pi](https://github.com/earendil-works/pi)
+installed as the `pi` command on your `PATH`.
+
+```bash
+npm install --global pi-tau-web-server
+```
+
+## Usage
+
+```bash
+pi-tau-web-server
+```
+
+Open the printed URL (default `http://localhost:3001`). Click `+` in the tab bar or sidebar to create an in-page Tau tab, choose or type a project directory, optionally enter a Pi `/model`-style model string, then chat.
+
+```bash
+pi-tau-web-server --host 127.0.0.1 --port 3001 --open
+TAU_PORT=3001 TAU_HOST=0.0.0.0 TAU_PROJECTS_DIR="$HOME/projects" pi-tau-web-server
+```
+
+## Containers
+
+The container launcher runs one isolated Tau service per instance name. Docker
+and Podman are supported; set `TAU_CONTAINER_RUNTIME` to select one explicitly.
+The image is built automatically on the first run, or it can be built ahead of
+time:
+
+```bash
+container/tau-container build
+```
+
+Start an instance with credentials in the environment:
+
+```bash
+TAU_USER=alice TAU_PASS='choose-a-password' \
+  container/tau-container run personal-workspace --port 3001
+```
+
+Missing credentials are prompted for, with the password input hidden. Start
+additional isolated instances by giving each one a different name and host
+port:
+
+```bash
+container/tau-container run work-workspace --port 3002
+container/tau-container status
+container/tau-container logs work-workspace
+container/tau-container stop work-workspace
+```
+
+Each instance has an isolated `~/projects` directory inside the container,
+available at `/state/home/projects`. It is mounted read-write from the
+instance's `projects/` state directory.
+
+On an instance's first launch, the launcher copies
+`${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}` into that instance's writable state.
+Symlinks are dereferenced on the host. The host `sessions/`, `npm/`, and `git/`
+directories are excluded. Package declarations remain in `settings.json`, so Pi
+installs missing npm/git packages when its first RPC session starts.
+
+The copied configuration is never refreshed automatically. Changes made by Pi
+or Tau therefore survive container recreation and remain isolated from other
+instances. Projects and session files are also stored separately per instance.
+By default, state is kept under:
+
+```text
+${XDG_DATA_HOME:-$HOME/.local/share}/pi-tau-web-server/instances/<instance>/
+```
+
+The host-side projects directory is `<instance>/projects/` beneath that path.
+Override the state root with `TAU_CONTAINER_STATE_DIR`.
+
+Ports bind to all host interfaces by default. HTTP Basic Auth does not encrypt
+credentials or traffic, so use a TLS reverse proxy for access from another
+machine. Pass `--bind 127.0.0.1` to restrict an instance to local access.
+
+## Features
+
+### Chat
+
+- Full markdown rendering with syntax-highlighted code blocks
+- Streaming responses with typing indicator
+- Image attachments (paste, drag & drop, or button)
+- Copy any message with one click
+- Inline diff viewer for edit tool calls
+- Message queuing while the agent is working
+
+### Live Session Management
+
+- Backend-owned live Pi RPC sessions, each backed by a `pi --mode rpc` subprocess
+- JupyterLab-style in-page Tau tab strip — each tab is an independent Pi session
+- Browser reload or reconnect restores live Tau tabs from the backend
+- Multiple browser clients see the same live session list
+- Historical sessions remain read-only
+- **Session tree and branching** — inspect the active session's full tree and jump to any earlier entry, mirroring Pi TUI's `/tree` behavior; choose a user message to restore it to the composer and create a new branch
+
+### Model & Thinking
+
+- Optional model string at session creation using Pi `/model` syntax (e.g. `openai/gpt-5.5:high`)
+- Per-session model picker with fuzzy search
+- Per-session thinking level controls
+- Token usage percentage with context window visualiser
+- Cost tracking per session
+
+### File Browser
+
+- Right sidebar rooted at the active live session's working directory
+- Navigate directories, open files natively
+- Drag files onto the input to insert their path
+
+### Session Browser
+
+- Sidebar with all saved Pi JSONL session files, grouped by project
+- Full-text search across all historical sessions with highlighted snippets
+- Rename sessions, export to HTML
+
+### Mobile Support
+
+- Slide-over sidebar with swipe-from-edge gesture
+- Slimmed header, model picker stays accessible
+- Larger touch targets and font sizes optimized for mobile
+- Auto-reconnect WebSocket on return from background
+- PWA: installable as a standalone app on iOS, Android, and macOS
+
+### Themes
+
+Six built-in themes: Dusk (clean neutral dark, default), Dawn (warm blue dark), Midnight (OLED black), Clean (Apple-style light with cyan-blue accents), Terracotta (warm light), Sage (warm olive-green). All with frosted glass header and input area.
+
+## Configuration
+
+### CLI flags
+
+| Flag                                  |                                                  Description |
+| ------------------------------------- | -----------------------------------------------------------: |
+| `--open`                              |                 Open the URL in the default browser on start |
+| `--port` / `TAU_PORT`                 |                                Server port (default: `3001`) |
+| `--host` / `TAU_HOST`                 |                            Bind address (default: `0.0.0.0`) |
+| `--projects-dir` / `TAU_PROJECTS_DIR` | Directory scanned for project chips in the new-session modal |
+
+### Environment variables
+
+| Variable           |     Default |                                              Description |
+| ------------------ | ----------: | -------------------------------------------------------: |
+| `TAU_PORT`         |      `3001` |                                              Server port |
+| `TAU_HOST`         |   `0.0.0.0` |                                             Bind address |
+| `TAU_PROJECTS_DIR` |    _(none)_ | Directory scanned for project chips in the new-tab modal |
+| `TAU_STATIC_DIR`   | _(bundled)_ |                               Override static files path |
+| `TAU_USER`         |    _(none)_ |                                 HTTP Basic Auth username |
+| `TAU_PASS`         |    _(none)_ |                                 HTTP Basic Auth password |
+| `TAU_COOKIE_SECRET`| _(generated)_ |            Secret that signs session cookies (optional) |
+
+Tau also reads matching values from `~/.pi/agent/settings.json` under the `tau` key (`host`, `port`, `projectsDir`, `user`, `pass`, `authEnabled`, `cookieSecret`).
+
+### Authentication
+
+Tau Web Server supports optional HTTP Basic Auth. Set credentials in `~/.pi/agent/settings.json` or via environment variables, then toggle "Require login" in Tau Settings.
+
+```json
+{
+  "tau": {
+    "user": "pi",
+    "pass": "your-password"
+  }
+}
+```
+
+Both HTTP and WebSocket connections are gated when enabled. `/api/health` remains open for monitoring.
+
+After the first successful Basic login, the server sets a signed `HttpOnly` session cookie and accepts it in place of the Authorization header. This keeps mobile browsers (notably iOS Safari and the installed PWA, which evict cached Basic credentials whenever you switch apps) from re-prompting for the password every time you return to the app. The cookie is scoped to the browser session — killing the browser ends it and the Basic prompt appears again — and the token inside it expires after 12 hours of inactivity, renewing itself while the app is in use. Changing the password invalidates every outstanding cookie on all devices, and deleting the auto-generated `cookieSecret` from `~/.pi/agent/settings.json` force-logs-out all devices at once.
+
+## How it works
+
+```
+┌─────────────┐     ┌──────────────────────────┐     ┌───────────────────────────┐
+│  Browser    │◄───►│  Tau Web Server          │◄───►│  pi --mode rpc            │
+│  (Tau UI)   │     │  HTTP + WebSocket +      │     │  child session 1          │
+│             │     │  LiveSessionManager      │     ├───────────────────────────┤
+│             │     │  (Node.js)               │     │  pi --mode rpc            │
+│             │     │                          │     │  child session 2          │
+│             │     │                          │     ├───────────────────────────┤
+│             │     │                          │     │  pi --mode rpc            │
+│             │     │                          │     │  child session (N)        │
+└─────────────┘     └──────────────────────────┘     └───────────────────────────┘
+```
+
+The browser connects to Tau Web Server over WebSocket (and HTTP for history and API calls). Tau manages a pool of `PiRpcSession` instances, each of which spawns a `pi --mode rpc` subprocess. Communication with Pi is over JSON line-delimited RPC via stdin/stdout. Closing an in-page Tau tab sends a DELETE request that terminates the corresponding Pi child. Shutting down Tau terminates all managed children.
+
+## Development
+
+### Prerequisites
+
+- [Pi](https://github.com/earendil-works/pi) must be installed (`pi` on `PATH`)
+- Node.js and npm
+
+### Setup
+
+```bash
+git clone https://github.com/milanglacier/pi-tau-web-server.git
+cd pi-tau-web-server
+npm install
+npm run build
+npm link
+pi-tau-web-server --projects-dir ~/code
+```
+
+The project is written in TypeScript, with separate `tsconfig.json` files:
+
+| Config                 |                                       Targets |
+| ---------------------- | --------------------------------------------: |
+| `tsconfig.server.json` |     Server-side code (`src/server/` → `bin/`) |
+| `tsconfig.public.json` | Browser-side code (`src/public/` → `public/`) |
+| `tsconfig.test.json`   |                          Test files (`test/`) |
+
+Compiled JS is not committed to git (see `.gitignore`). Always run `npm run build` (or `tsc -p <config>`) after editing TypeScript source.
+
+Edit `public/` files and refresh the browser. Restart `pi-tau-web-server` after changing server code in `src/server/`.
+
+### Tests
+
+```bash
+npm test
+```
+
+The test suite uses Node.js built-in `node --test` and covers session-file path validation, the `PiRpcSession` state machine, `LiveSessionManager`, the `/api/rpc` shim, HTTP + WebSocket server surface (including same-origin/CORS hardening and malformed-URL hardening), and WebSocket auth gating.
+
+Each test file points `PI_CODING_AGENT_DIR` at an isolated temp tree so real Pi settings and sessions are never touched. The `LiveSessionManager` tests replace the real `spawn` with a test stub.
+
+### Project structure
+
+```
+├── bin/            # Compiled server-side JS
+├── public/         # Compiled browser-side JS, HTML, CSS, icons
+├── src/
+│   ├── server/     # Server TypeScript source
+│   │   ├── server-main.ts   # HTTP server, WebSocket, API routes
+│   │   ├── sessions.ts      # PiRpcSession + LiveSessionManager
+│   │   ├── model-utils.ts   # Model parsing and formatting
+│   │   ├── config.ts        # Settings, paths, CLI args
+│   │   └── types.ts         # Shared type definitions
+│   └── public/     # Browser TypeScript source
+│       ├── app.ts, app-main.ts, state.ts, themes.ts, ...
+│       └── websocket-client.ts
+├── test/           # Node.js test files
+├── docs/           # Screenshots and documentation
+└── extras/         # Extra utilities
+```
+
+## License
+
+MIT

package/bin/auth.js

@@ -0,0 +1,96 @@
+"use strict";
+/*
+ * Session-cookie auth on top of HTTP Basic.
+ *
+ * iOS Safari (and the installed PWA) evicts cached Basic credentials when the
+ * user switches apps, so Basic alone re-prompts on every return. After a
+ * successful Basic request the server mints a signed, stateless session token
+ * carried in a browser-session cookie (no Max-Age): it survives app switching
+ * but ends with the browser session, and the embedded expiry bounds its life
+ * even if the browser restores session cookies with restored tabs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_REFRESH_THRESHOLD_SECONDS = exports.SESSION_TTL_SECONDS = exports.SESSION_COOKIE_NAME = void 0;
+exports.issueSessionToken = issueSessionToken;
+exports.verifySessionToken = verifySessionToken;
+exports.parseCookies = parseCookies;
+exports.buildSessionCookie = buildSessionCookie;
+const crypto = require('node:crypto');
+const config_js_1 = require("./config.js");
+exports.SESSION_COOKIE_NAME = 'tau_session';
+exports.SESSION_TTL_SECONDS = 12 * 3600;
+exports.SESSION_REFRESH_THRESHOLD_SECONDS = 6 * 3600;
+let cachedSecret = '';
+// Lazy so installs that never enable auth never write settings.json.
+function getCookieSecret() {
+    if (cachedSecret)
+        return cachedSecret;
+    if (config_js_1.TAU_SETTINGS.cookieSecret) {
+        cachedSecret = config_js_1.TAU_SETTINGS.cookieSecret;
+        return cachedSecret;
+    }
+    cachedSecret = crypto.randomBytes(32).toString('hex');
+    if (!(0, config_js_1.saveTauSetting)('cookieSecret', cachedSecret)) {
+        console.warn('tau: could not persist tau.cookieSecret to settings.json; session cookies will not survive a server restart (every restart will log all devices out). Set TAU_COOKIE_SECRET to work around this.');
+    }
+    return cachedSecret;
+}
+// Recomputed per call so tokens die when the credentials change. The newline
+// separator cannot appear in either field, unlike ':' which passwords allow.
+function credentialFingerprint() {
+    return crypto.createHash('sha256').update(config_js_1.TAU_SETTINGS.user + '\n' + config_js_1.TAU_SETTINGS.pass).digest('hex');
+}
+function signToken(expiresAtSeconds) {
+    return crypto.createHmac('sha256', getCookieSecret())
+        .update('v1.' + expiresAtSeconds + '.' + credentialFingerprint())
+        .digest('base64url');
+}
+function issueSessionToken(expiresAtSeconds) {
+    const expires = expiresAtSeconds ?? Math.floor(Date.now() / 1000) + exports.SESSION_TTL_SECONDS;
+    return 'v1.' + expires + '.' + signToken(expires);
+}
+function verifySessionToken(token) {
+    const invalid = { valid: false, expiresAt: 0 };
+    try {
+        const parts = String(token).split('.');
+        if (parts.length !== 3 || parts[0] !== 'v1')
+            return invalid;
+        const expiresAt = parseInt(parts[1], 10);
+        if (!Number.isFinite(expiresAt) || expiresAt <= Math.floor(Date.now() / 1000))
+            return invalid;
+        const expected = Buffer.from(signToken(expiresAt));
+        const actual = Buffer.from(parts[2]);
+        if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual))
+            return invalid;
+        return { valid: true, expiresAt };
+    }
+    catch {
+        return invalid;
+    }
+}
+// Manual parser because the WebSocket upgrade path has no framework.
+function parseCookies(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name)
+            continue;
+        try {
+            out[name] = decodeURIComponent(part.slice(eq + 1).trim());
+        }
+        catch { }
+    }
+    return out;
+}
+// No Max-Age/Expires on purpose: a browser-session cookie is dropped when the
+// browser session ends, so killing the browser re-prompts for Basic auth.
+function buildSessionCookie(token, opts) {
+    if (opts.clear)
+        return `${exports.SESSION_COOKIE_NAME}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`;
+    return `${exports.SESSION_COOKIE_NAME}=${token}; Path=/; HttpOnly; SameSite=Lax` + (opts.secure ? '; Secure' : '');
+}

package/bin/config.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIME_TYPES = exports.STATIC_DIR = exports.HOST = exports.PORT = exports.AUTH_CONFIGURED = exports.TAU_SETTINGS = exports.SESSIONS_DIR = exports.PI_AGENT_DIR = exports.USER_HOME = exports.ARGS = void 0;
+exports.parseArgs = parseArgs;
+exports.expandHome = expandHome;
+exports.loadTauSettings = loadTauSettings;
+exports.saveTauSetting = saveTauSetting;
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const key = arg.slice(2);
+        if (key === 'open') {
+            out.open = true;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+            out[key] = next;
+            i++;
+        }
+    }
+    return out;
+}
+exports.ARGS = parseArgs(process.argv.slice(2));
+exports.USER_HOME = process.env.HOME || process.env.USERPROFILE || os.homedir();
+exports.PI_AGENT_DIR = process.env.PI_CODING_AGENT_DIR || path.join(exports.USER_HOME, '.pi', 'agent');
+exports.SESSIONS_DIR = process.env.PI_CODING_AGENT_SESSION_DIR || path.join(exports.PI_AGENT_DIR, 'sessions');
+function expandHome(p) {
+    if (!p || typeof p !== 'string')
+        return p;
+    return p.startsWith('~') ? path.join(exports.USER_HOME, p.slice(1)) : p;
+}
+function loadTauSettings() {
+    let settings = {};
+    try {
+        const settingsPath = path.join(exports.PI_AGENT_DIR, 'settings.json');
+        settings = (JSON.parse(fs.readFileSync(settingsPath, 'utf8')).tau || {});
+    }
+    catch { }
+    return {
+        port: parseInt(String(exports.ARGS.port || process.env.TAU_PORT || settings.port || '3001'), 10),
+        host: exports.ARGS.host || process.env.TAU_HOST || settings.host || '0.0.0.0',
+        user: process.env.TAU_USER || settings.user || '',
+        pass: process.env.TAU_PASS || settings.pass || '',
+        authEnabled: settings.authEnabled,
+        cookieSecret: process.env.TAU_COOKIE_SECRET || settings.cookieSecret || '',
+        projectsDir: expandHome(exports.ARGS['projects-dir'] || process.env.TAU_PROJECTS_DIR || settings.projectsDir || ''),
+    };
+}
+exports.TAU_SETTINGS = loadTauSettings();
+exports.AUTH_CONFIGURED = !!(exports.TAU_SETTINGS.user && exports.TAU_SETTINGS.pass);
+exports.PORT = exports.TAU_SETTINGS.port;
+exports.HOST = exports.TAU_SETTINGS.host;
+exports.STATIC_DIR = process.env.TAU_STATIC_DIR || findPublicDir();
+function findPublicDir() {
+    const candidates = [];
+    const add = (p) => candidates.push(path.resolve(p));
+    add(path.join(__dirname, '..', 'public'));
+    add(path.join(process.cwd(), 'public'));
+    try {
+        const pkgPath = require.resolve('pi-tau-web-server/package.json');
+        add(path.join(path.dirname(pkgPath), 'public'));
+    }
+    catch { }
+    add(path.join(process.cwd(), 'node_modules', 'pi-tau-web-server', 'public'));
+    return candidates.find((c) => fs.existsSync(path.join(c, 'index.html'))) || candidates[0];
+}
+exports.MIME_TYPES = {
+    '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+    '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
+    '.svg': 'image/svg+xml', '.ico': 'image/x-icon', '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+function saveTauSetting(key, value) {
+    const settingsPath = path.join(exports.PI_AGENT_DIR, 'settings.json');
+    try {
+        let settings = {};
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        }
+        catch { }
+        if (!settings.tau)
+            settings.tau = {};
+        settings.tau[key] = value;
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/bin/model-utils.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelLabel = modelLabel;
+exports.normalizeModel = normalizeModel;
+exports.parseModelSpecToModel = parseModelSpecToModel;
+exports.parseYesNo = parseYesNo;
+exports.parsePiListModels = parsePiListModels;
+exports.execFileAsync = execFileAsync;
+exports.getAvailableModels = getAvailableModels;
+exports._setExecFileForTest = _setExecFileForTest;
+exports._clearModelListCacheForTest = _clearModelListCacheForTest;
+const { execFile } = require('node:child_process');
+function modelLabel(model, fallback = '') {
+    if (!model)
+        return fallback || '';
+    if (typeof model === 'string')
+        return model;
+    if (model.provider && model.id)
+        return `${model.provider}/${model.id}`;
+    return model.id || model.name || fallback || '';
+}
+// Normalize any model value into the canonical form: null or a full
+// {provider, id, ...} object. Bare `provider/id` strings (and "id" strings
+// with no slash) are parsed into objects; anything unrecognizable becomes null.
+function normalizeModel(value) {
+    if (!value)
+        return null;
+    if (typeof value === 'object') {
+        const record = value;
+        if (record.provider && record.id)
+            return { ...record };
+        if (record.id)
+            return { ...record, provider: record.provider || '' };
+        return null;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        const slashIdx = trimmed.indexOf('/');
+        if (slashIdx === -1)
+            return { provider: '', id: trimmed };
+        const provider = trimmed.slice(0, slashIdx);
+        const id = trimmed.slice(slashIdx + 1);
+        if (!id)
+            return null;
+        return { provider, id };
+    }
+    return null;
+}
+// Parse a `provider/id[:level]` spec string (as passed on session creation or
+// the model-input box) into a canonical {provider, id} object plus an optional
+// thinking level. Returns {model, level} where `model` is null when unparseable.
+function parseModelSpecToModel(spec) {
+    const trimmed = String(spec || '').trim();
+    if (!trimmed)
+        return { model: null, level: null };
+    let level = null;
+    const colonIdx = trimmed.lastIndexOf(':');
+    if (colonIdx !== -1) {
+        const candidate = trimmed.slice(colonIdx + 1).toLowerCase();
+        if (['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(candidate)) {
+            level = candidate;
+        }
+    }
+    const core = (colonIdx !== -1 && level) ? trimmed.slice(0, colonIdx) : trimmed;
+    return { model: normalizeModel(core), level };
+}
+function parseYesNo(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'yes')
+        return true;
+    if (normalized === 'no')
+        return false;
+    return value;
+}
+function parsePiListModels(output) {
+    const lines = String(output || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const models = [];
+    for (const line of lines) {
+        if (/^provider\s+model\s+/i.test(line))
+            continue;
+        const parts = line.split(/\s{2,}/).map((part) => part.trim()).filter(Boolean);
+        if (parts.length < 2)
+            continue;
+        const [provider, id, context, maxOutput, thinking, images] = parts;
+        if (!provider || !id)
+            continue;
+        models.push({
+            provider,
+            id,
+            ...(context !== undefined ? { context } : {}),
+            ...(maxOutput !== undefined ? { maxOutput } : {}),
+            ...(thinking !== undefined ? { thinking: parseYesNo(thinking) } : {}),
+            ...(images !== undefined ? { images: parseYesNo(images) } : {}),
+        });
+    }
+    return models;
+}
+const MODEL_LIST_CACHE_MS = 5 * 60 * 1000;
+let modelListCache = { at: 0, models: [] };
+let _execFileForTest = null;
+function execFileAsync(file, args, opts) {
+    const runner = _execFileForTest || execFile;
+    return new Promise((resolve, reject) => {
+        runner(file, args, opts, (err, stdout, stderr) => {
+            if (err) {
+                err.stderr = stderr;
+                reject(err);
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+async function getAvailableModels() {
+    const now = Date.now();
+    if (modelListCache.at && now - modelListCache.at < MODEL_LIST_CACHE_MS) {
+        return modelListCache.models;
+    }
+    try {
+        const { stdout } = await execFileAsync('pi', ['--list-models'], { timeout: 30000, encoding: 'utf8' });
+        const models = parsePiListModels(stdout);
+        modelListCache = { at: now, models };
+        return models;
+    }
+    catch (err) {
+        console.warn('[Tau] Failed to list Pi models:', err instanceof Error ? err.message : err);
+        modelListCache = { at: now, models: modelListCache.models || [] };
+        return modelListCache.models;
+    }
+}
+function _setExecFileForTest(fn) { _execFileForTest = fn || null; modelListCache = { at: 0, models: [] }; }
+function _clearModelListCacheForTest() { modelListCache = { at: 0, models: [] }; }