claude-simple 0.2.27 → 0.2.30

package/src/app.js

@@ -33,10 +33,13 @@ import { discoverAllAgentModels } from './agents/models.js';
 import { createTextBatcher } from './agents/stream-batch.js';
 import { normalizeCommand, mapAgentEmit } from './runtime/protocol.js';
 import { createOutbox } from './runtime/outbox.js';
+import { broadcastChatFrame } from './runtime/chat-broadcast.js';
 import { createExternalSessionMirror } from './runtime/external-session-sync.js';
 import { resolveApproval, cancelApprovalsForSession } from './runtime/approvals.js';
 import { createMcpHttpHandler, createMcpService } from './mcp.js';
 import { createCollab, roleAtLeast, proxyToLocalPort, machineId as localMachineId } from './collab.js';
+import { createQuotaReader } from './agent-quota.js';
+import { parseHistoryQuery, sliceHistoryMessages } from './session-history.js';
 import {
   CLAUDE_ENV_KEYS,
   loadAgentEnvDoc,
@@ -48,6 +51,17 @@ import {
   normalizeProfileName,
   envForProfile,
 } from './agent-env.js';
+import {
+  containedPath,
+  defaultInteractiveShell,
+  expandHome,
+  processKillSignal,
+  resolveWinExecutable,
+  shellExecSpec,
+  spawnCommandOpts,
+  userLocalBinDirs,
+} from './platform.js';
+import { canonicalizeProjectApiPath } from './project-api-path.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.join(__dirname, '..');
 
@@ -62,18 +76,28 @@ const SESSION_META_FILE  = process.env.SESSION_META_FILE  || path.join(rootDir,
 // without requiring the service unit to mirror an interactive shell PATH.
 function resolveUserLocalCommand(configured, fallback) {
   const command = configured || fallback;
-  if (command.includes('/') || command.includes('\\')) return command.replace(/^~/, os.homedir());
-  for (const dir of [path.join(os.homedir(), '.local', 'bin'), path.join(os.homedir(), 'bin')]) {
+  if (command.includes('/') || command.includes('\\')) return expandHome(command);
+  for (const dir of userLocalBinDirs()) {
     const candidate = path.join(dir, command);
     if (fsSync.existsSync(candidate)) return candidate;
+    if (process.platform === 'win32') {
+      for (const ext of ['.cmd', '.exe', '.bat']) {
+        if (fsSync.existsSync(candidate + ext)) return candidate + ext;
+      }
+    }
   }
   return command;
 }
-const CLAUDE_CLI_PATH = process.env.CLAUDE_CLI_PATH || 'claude';
-const CODEX_CLI_PATH  = process.env.CODEX_CLI_PATH  || 'codex';
-const GROK_CLI_PATH   = process.env.GROK_CLI_PATH   || 'grok';
-const GEMINI_CLI_PATH = resolveUserLocalCommand(process.env.GEMINI_CLI_PATH || process.env.AGY_PATH, 'agy');
-const CURSOR_AGENT_PATH = process.env.CURSOR_AGENT_PATH || 'cursor-agent';
+function resolveAgentCommand(configured, fallback) {
+  const local = resolveUserLocalCommand(configured, fallback);
+  return resolveWinExecutable(local, { extraDirs: userLocalBinDirs() });
+}
+
+const CLAUDE_CLI_PATH = resolveAgentCommand(process.env.CLAUDE_CLI_PATH, 'claude');
+const CODEX_CLI_PATH  = resolveAgentCommand(process.env.CODEX_CLI_PATH, 'codex');
+const GROK_CLI_PATH   = resolveAgentCommand(process.env.GROK_CLI_PATH, 'grok');
+const GEMINI_CLI_PATH = resolveAgentCommand(process.env.GEMINI_CLI_PATH || process.env.AGY_PATH, 'agy');
+const CURSOR_AGENT_PATH = resolveAgentCommand(process.env.CURSOR_AGENT_PATH, 'cursor-agent');
 const CODEX_HOME = (process.env.CODEX_HOME || path.join(os.homedir(), '.codex')).replace(/^~/, os.homedir());
 const GROK_HOME  = (process.env.GROK_HOME  || path.join(os.homedir(), '.grok')).replace(/^~/, os.homedir());
 const GEMINI_HOME = (process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini')).replace(/^~/, os.homedir());
@@ -285,20 +309,20 @@ function authMiddleware(req, res, next) {
 // ─── Path helpers ─────────────────────────────────────────────────────────────
 function safePath(base, rel) {
   const resolved = path.resolve(base, rel || '');
-  if (!resolved.startsWith(path.resolve(base))) throw new Error('Path traversal');
+  if (!containedPath(base, resolved)) throw new Error('Path traversal');
   return resolved;
 }
 
 function expandPath(p) {
-  if (!p) return p;
-  return p.replace(/^~/, os.homedir());
+  return expandHome(p);
 }
 
 function resolveProjectRoot(req) {
   const root = req.query.root || req.body?.root;
   if (root) {
     const resolved = path.resolve(expandPath(root));
-    if (!path.isAbsolute(resolved) || resolved === '/' || resolved.includes('\0'))
+    const driveRoot = path.parse(resolved).root;
+    if (!path.isAbsolute(resolved) || resolved === '/' || resolved === driveRoot || resolved.includes('\0'))
       throw new Error('Invalid root path');
     return resolved;
   }
@@ -308,7 +332,7 @@ function resolveProjectRoot(req) {
 // ─── Git helpers ──────────────────────────────────────────────────────────────
 function git(args, cwd) {
   return new Promise((resolve, reject) => {
-    const child = spawn('git', args, { cwd, shell: false });
+    const child = spawn('git', args, { cwd, ...spawnCommandOpts() });
     let out = '', err = '';
     child.stdout.on('data', d => out += d);
     child.stderr.on('data', d => err += d);
@@ -336,17 +360,8 @@ function sendJson(ws, data) {
   }
 }
 
-function broadcastChat(sessionId, data, fallbackWs) {
-  let n = 0;
-  if (sessionId) {
-    for (const c of chatClients) {
-      if (c.sessionId === sessionId) {
-        sendJson(c.ws, data);
-        n++;
-      }
-    }
-  }
-  if (n === 0 && fallbackWs) sendJson(fallbackWs, data);
+function broadcastChat(sessionId, data, ownerWs) {
+  broadcastChatFrame(chatClients, sessionId, data, ownerWs, sendJson);
 }
 
 async function listSessions(filterCwd = null, agentFilter = null) {
@@ -505,7 +520,15 @@ function compactHistoryMessages(messages) {
 
 // ─── App factory ──────────────────────────────────────────────────────────────
 export function createApp() {
+  const readQuota = createQuotaReader({ claudePath: CLAUDE_CLI_PATH, codexPath: CODEX_CLI_PATH, codexHome: CODEX_HOME,
+    grokHome: GROK_HOME, defaultClaudeDir: CLAUDE_CONFIG_DIRS[0], allowedClaudeDirs: () => CLAUDE_CONFIG_DIRS });
   const app = express();
+  app.use((req, _res, next) => {
+    const pathOnly = (req.url || '').split('?')[0];
+    const canon = canonicalizeProjectApiPath(pathOnly);
+    if (canon !== pathOnly) req.url = canon + (req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '');
+    next();
+  });
   const COLLAB_FILE = process.env.COLLAB_FILE || path.join(rootDir, '.collab.json');
   const collab = createCollab({ filePath: COLLAB_FILE });
   const allowRemoteProxy = process.env.PORT_PROXY_ALLOW_REMOTE === '1';
@@ -626,7 +649,12 @@ export function createApp() {
     })().catch(e => res.status(500).json({ error: e.message }));
   });
 
-  app.use(express.json({ limit: '10mb' }));
+  const jsonBodyParser = express.json({ limit: '10mb' });
+  app.use((req, res, next) => {
+    // Proxy bodies belong to the target app, including arbitrary JSON bytes.
+    if (req.path === '/api/port-proxy' || req.path.startsWith('/r/')) return next();
+    return jsonBodyParser(req, res, next);
+  });
 
   // MCP uses a separate short-lived bearer token. Normal UI JWTs deliberately
   // cannot call /mcp, so a browser token leaked through a URL cannot become an
@@ -988,6 +1016,14 @@ export function createApp() {
     }
   });
 
+  app.get('/api/agents/quota', authMiddleware, async (req, res) => {
+    res.setHeader('Cache-Control', 'private, no-store');
+    const agent = req.query.agent;
+    if (!['claude', 'codex', 'grok'].includes(agent)) return res.status(400).json({ error: 'Unsupported agent' });
+    try { res.json(await readQuota({ agent, configDir: req.query.configDir })); }
+    catch { res.status(400).json({ error: 'Unknown Claude config directory' }); }
+  });
+
   app.get('/api/projects/:id/files', authMiddleware, async (req, res) => {
     try {
       const projectPath = resolveProjectRoot(req);
@@ -1321,10 +1357,12 @@ export function createApp() {
         const since = Date.now() - days * 86400000;
         sessions = sessions.filter(s => (s.updatedAt || 0) >= since);
       }
+      const offset = Math.max(0, parseInt(req.query.offset || '0', 10) || 0);
+      sessions = sessions.slice(offset);
       if (limit > 0 && sessions.length > limit) sessions = sessions.slice(0, limit);
       const etag = `"s${crypto.createHash('sha1').update(JSON.stringify(sessions)).digest('base64url').slice(0, 20)}"`;
       res.setHeader('ETag', etag);
-      res.setHeader('Cache-Control', 'private, max-age=15');
+      res.setHeader('Cache-Control', 'private, no-store, no-cache');
       if (req.headers['if-none-match'] === etag) return res.status(304).end();
       res.json(sessions);
     } catch (e) {
@@ -1376,11 +1414,9 @@ export function createApp() {
       const { sessionId } = req.params;
       if (!/^[0-9a-f-]{36}$/i.test(sessionId)) return res.status(400).json({ error: 'Invalid session id' });
       const preferred = typeof req.query.agent === 'string' ? req.query.agent : null;
-      // tail=0 → full history (default). Positive = last N messages only.
-      let tail = parseInt(req.query.tail ?? '0', 10);
-      if (Number.isNaN(tail)) tail = 0;
-      if (tail < 0) tail = 0;
-      if (tail > 50_000) tail = 50_000;
+      // tail=0 → full history (default). Positive = last N. before = exclusive
+      // end index for older pages (scroll-up).
+      const { tail, before } = parseHistoryQuery(req.query);
       const compact = req.query.compact !== '0' && req.query.compact !== 'false';
       const opts = {
         claudeConfigDirs: CLAUDE_CONFIG_DIRS,
@@ -1403,20 +1439,16 @@ export function createApp() {
       let messages = Array.isArray(bundle)
         ? bundle
         : (bundle.messages || []);
-      const total = messages.length;
-      let truncated = false;
-      if (tail > 0 && messages.length > tail) {
-        messages = messages.slice(-tail);
-        truncated = true;
-      }
-      if (compact) messages = compactHistoryMessages(messages);
+      const page = sliceHistoryMessages(messages, { tail, before });
+      messages = compact ? compactHistoryMessages(page.messages) : page.messages;
       const payload = {
         messages,
         context: Array.isArray(bundle) ? null : (bundle.context || null),
         agent: Array.isArray(bundle) ? (preferred || 'claude') : (bundle.agent || preferred || 'claude'),
-        total,
-        truncated,
-        tail: truncated ? tail : total,
+        total: page.total,
+        truncated: page.truncated,
+        oldestIndex: page.oldestIndex,
+        tail: page.tail,
         compact,
       };
       res.setHeader('X-Session-Agent', payload.agent);
@@ -1552,6 +1584,27 @@ export function createApp() {
     }
   });
 
+  app.get('/api/sessions/:sessionId/jsonl', authMiddleware, async (req, res) => {
+    try {
+      const { sessionId } = req.params;
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) {
+        return res.status(400).json({ error: 'Invalid session id' });
+      }
+      const agent = typeof req.query.agent === 'string' ? req.query.agent : null;
+      if (agent && !['claude', 'codex', 'grok', 'gemini', 'cursor'].includes(agent)) {
+        return res.status(400).json({ error: 'Invalid agent' });
+      }
+      const result = await loadSessionJsonl(sessionId, agent, {
+        claudeConfigDirs: CLAUDE_CONFIG_DIRS, codexHome: CODEX_HOME,
+        grokHome: GROK_HOME, geminiHome: GEMINI_HOME, cursorHome: CURSOR_HOME,
+      }, { offset: req.query.offset, maxLines: req.query.limit,
+        tail: req.query.tail === '1', maxChars: req.query.maxChars });
+      if (!result) return res.status(404).json({ error: 'Session JSONL not found' });
+      res.setHeader('Cache-Control', 'no-store');
+      res.json({ ...result, sessionId, running: isSessionBusy(sessionId) });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
   app.get('/api/sessions/:sessionId/memory/file', authMiddleware, async (req, res) => {
     try {
       const { sessionId } = req.params;
@@ -2116,10 +2169,11 @@ export function createApp() {
         const shellCmd = cmd.command || '';
         const cwd = cmd.cwd || os.homedir();
         wireSend({ type: 'shell-start', command: shellCmd });
-        shellProc = spawn(process.env.SHELL || 'bash', ['-c', shellCmd], {
+        const spec = shellExecSpec(shellCmd);
+        shellProc = spawn(spec.bin, spec.args, {
           cwd,
           env: { ...process.env },
-          shell: false,
+          ...spawnCommandOpts({ extra: { shell: false } }),
         });
         shellOut = createTextBatcher(
           (data) => wireSend({ type: 'shell-output', stream: 'stdout', data }),
@@ -2178,17 +2232,21 @@ export function createApp() {
 
     let proc;
     let hasPython = false;
-    try {
-      execSync('python3 --version', { stdio: 'ignore' });
-      hasPython = true;
-    } catch {}
+    const win = process.platform === 'win32';
+    if (!win) {
+      try {
+        execSync('python3 --version', { stdio: 'ignore' });
+        hasPython = true;
+      } catch {}
+    }
 
     const cols = parseInt(url.searchParams.get('cols') || '80', 10);
     const rows = parseInt(url.searchParams.get('rows') || '24', 10);
 
     try {
-      const shellBin = process.env.SHELL || 'zsh';
-      if (hasPython) {
+      const interactive = defaultInteractiveShell();
+      const shellBin = interactive.bin;
+      if (hasPython && !win) {
         const pythonScript = `
 import os, pty, sys, termios, fcntl, struct, select
 shell = '${shellBin}'
@@ -2229,14 +2287,16 @@ else:
           stdio: ['pipe', 'pipe', 'pipe'],
         });
       } else {
-        const args = ['-i'];
-        if (shellBin.includes('bash')) {
+        const args = [...interactive.args];
+        if (!win && !args.length) args.push('-i');
+        if (!win && shellBin.includes('bash')) {
           args.push('--norc', '--noprofile');
         }
         proc = spawn(shellBin, args, {
           cwd: fsSync.existsSync(cwd) ? cwd : os.homedir(),
           env: { ...process.env, TERM: 'xterm-256color', PS1: '\\[\\033[32m\\]\\w\\[\\033[0m\\]$ ', HISTFILE: '' },
           stdio: ['pipe', 'pipe', 'pipe'],
+          ...spawnCommandOpts({ extra: { shell: false } }),
         });
       }
     } catch (e) {
@@ -2263,7 +2323,7 @@ else:
       }
     });
 
-    ws.on('close', () => { outBatch.flush(); try { proc.kill('SIGHUP'); } catch {} });
+    ws.on('close', () => { outBatch.flush(); try { proc.kill(processKillSignal()); } catch {} });
     ws.on('error', e => console.error('[ws/shell]', e.message));
   });
 

package/src/auto-update.js

@@ -80,6 +80,8 @@ function runNpmInstall(mode, pkgName, version, cwd) {
       cwd: mode === 'global' ? osHomedir() : cwd,
       env: process.env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      shell: process.platform === 'win32',
+      windowsHide: process.platform === 'win32',
     });
     let out = '';
     let err = '';

package/src/collab.js

@@ -250,6 +250,8 @@ export function proxyToLocalPort({ host, port, reqPath, method, headers, body, a
     }, (res) => {
       const chunks = [];
       res.on('data', c => chunks.push(c));
+      res.on('error', reject);
+      res.on('aborted', () => reject(new Error('upstream response aborted')));
       res.on('end', () => resolve({
         status: res.statusCode,
         headers: res.headers,
@@ -257,6 +259,7 @@ export function proxyToLocalPort({ host, port, reqPath, method, headers, body, a
       }));
     });
     r.on('error', reject);
+    r.on('timeout', () => r.destroy(new Error('upstream request timed out')));
     if (body && body.length) r.write(body);
     r.end();
   });

package/src/platform.js

@@ -0,0 +1,133 @@
+/**
+ * OS helpers so Edge can run on Windows as well as macOS/Linux.
+ * Unix remains the default; Windows gets cmd/PowerShell, .cmd spawn, and
+ * case-insensitive path checks.
+ */
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+
+export function isWin(platform = process.platform) {
+  return platform === 'win32';
+}
+
+export function expandHome(p, home = os.homedir()) {
+  if (!p) return p;
+  if (p === '~') return home;
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(home, p.slice(2));
+  return p;
+}
+
+function normalizeForCompare(p, platform) {
+  let s = String(p);
+  if (isWin(platform)) s = s.replace(/[/\\]+/g, '\\').replace(/\\+$/, '');
+  else s = path.normalize(s);
+  return isWin(platform) ? s.toLowerCase() : s;
+}
+
+export function pathsEqual(a, b, platform = process.platform) {
+  if (a == null || b == null) return a === b;
+  return normalizeForCompare(a, platform) === normalizeForCompare(b, platform);
+}
+
+/** True if `resolved` is `base` or a descendant (not a sibling prefix). */
+export function containedPath(base, resolved, platform = process.platform) {
+  const b = path.resolve(base);
+  const r = path.resolve(resolved);
+  const rel = path.relative(b, r);
+  if (!rel) return true;
+  if (path.isAbsolute(rel)) return false;
+  const first = rel.split(/[/\\]/)[0];
+  if (first === '..') return false;
+  if (isWin(platform) && rel.toLowerCase().startsWith('..')) return false;
+  return true;
+}
+
+export function defaultInteractiveShell({ platform = process.platform, env = process.env } = {}) {
+  if (isWin(platform)) {
+    const comspec = env.ComSpec || env.COMSPEC;
+    const shellEnv = env.SHELL || '';
+    // Git Bash sets SHELL=...\bash.exe; Edge still wants a native Windows shell.
+    if (shellEnv && /\.(exe|cmd|bat)$/i.test(shellEnv) && !/(^|[\\/])(bash|zsh|sh|dash|fish)(\.exe)?$/i.test(shellEnv)) {
+      return { bin: shellEnv, args: [] };
+    }
+    const sysroot = env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows';
+    const ps = path.join(sysroot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    if (fs.existsSync(ps)) {
+      return { bin: ps, args: ['-NoLogo', '-NoExit'] };
+    }
+    return { bin: comspec || path.join(sysroot, 'System32', 'cmd.exe'), args: [] };
+  }
+  return { bin: env.SHELL || 'zsh', args: ['-i'] };
+}
+
+export function shellExecSpec(command, { platform = process.platform, env = process.env } = {}) {
+  if (isWin(platform)) {
+    const sysroot = env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows';
+    const cmd = env.ComSpec || env.COMSPEC || path.join(sysroot, 'System32', 'cmd.exe');
+    return { bin: cmd, args: ['/d', '/s', '/c', command] };
+  }
+  const bin = env.SHELL || 'bash';
+  return { bin, args: ['-c', command] };
+}
+
+export function spawnCommandOpts({ platform = process.platform, extra = {} } = {}) {
+  if (isWin(platform)) {
+    return { shell: true, windowsHide: true, ...extra };
+  }
+  return { shell: false, ...extra };
+}
+
+export function processKillSignal(platform = process.platform) {
+  return isWin(platform) ? 'SIGTERM' : 'SIGHUP';
+}
+
+export function userLocalBinDirs(home = os.homedir(), platform = process.platform) {
+  const dirs = [
+    path.join(home, '.local', 'bin'),
+    path.join(home, 'bin'),
+    path.join(home, '.grok', 'bin'),
+  ];
+  if (isWin(platform)) {
+    dirs.push(
+      path.join(home, 'AppData', 'Roaming', 'npm'),
+      path.join(home, 'AppData', 'Local', 'npm'),
+    );
+  }
+  return dirs;
+}
+
+/**
+ * Resolve a bare command to an absolute .exe/.cmd on Windows so agents can be
+ * spawned with stdio pipes and shell:false. Unix returns the name unchanged.
+ */
+export function resolveWinExecutable(command, {
+  platform = process.platform,
+  env = process.env,
+  extraDirs = [],
+  exists = fs.existsSync,
+} = {}) {
+  if (!command) return command;
+  if (!isWin(platform)) return command;
+  if (command.includes('/') || command.includes('\\') || /\.[a-z0-9]+$/i.test(command)) {
+    return expandHome(command, env.USERPROFILE || env.HOME);
+  }
+  const exts = String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+    .split(';')
+    .map(e => e.trim())
+    .filter(Boolean);
+  const pathDirs = String(env.PATH || '').split(';').map(d => d.trim()).filter(Boolean);
+  const dirs = [...extraDirs, ...pathDirs];
+  for (const dir of dirs) {
+    for (const ext of ['', ...exts]) {
+      const candidate = path.join(dir, command + ext);
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return command;
+}
+
+export function spawnAgentOpts({ platform = process.platform } = {}) {
+  if (isWin(platform)) return { shell: false, windowsHide: true };
+  return { shell: false };
+}

package/src/project-api-path.js

@@ -0,0 +1,14 @@
+/**
+ * Files/git APIs take the real directory in ?root=. The :id path segment is
+ * unused. Clients that put a Windows cwd (C:\\Users\\... or C:/Users/...) into
+ * :id make extra slashes; Hub/Express then 404. Collapse those to `_`.
+ */
+export function canonicalizeProjectApiPath(pathname) {
+  const m = String(pathname || '').match(
+    /^(\/api\/projects\/)(.+)\/(files|file|git\/(?:status|diff|log))$/,
+  );
+  if (!m) return pathname;
+  const id = m[2];
+  if (!/[\\/:]/.test(id)) return pathname;
+  return `${m[1]}_/${m[3]}`;
+}

package/src/runtime/chat-broadcast.js

@@ -0,0 +1,12 @@
+// The run owner (including a Hub task tunnel) must receive every frame even
+// when it has not subscribed to the newly assigned native session ID.
+export function broadcastChatFrame(clients, sessionId, data, ownerWs, send) {
+  const recipients = new Set();
+  if (ownerWs) recipients.add(ownerWs);
+  if (sessionId) {
+    for (const client of clients) {
+      if (client.sessionId === sessionId) recipients.add(client.ws);
+    }
+  }
+  for (const ws of recipients) send(ws, data);
+}

package/src/runtime/port-websocket.js

@@ -0,0 +1,80 @@
+import { WebSocket } from 'ws';
+import { isLoopbackHost } from '../collab.js';
+
+const MAX_FRAME = 16 * 1024 * 1024;
+const validClose = code => code === 1000 || code === 1001 || code === 1002 || code === 1003 ||
+  (code >= 1007 && code <= 1014) || (code >= 3000 && code <= 4999);
+
+// Separate from agent tunnels: arbitrary application frames must remain opaque.
+export function createPortWebSocketRelay(send, { allowRemote = false } = {}) {
+  const sockets = new Map();
+  function handle(msg) {
+    if (!msg.type?.startsWith('port-ws-')) return false;
+    const id = msg.tunnelId;
+    if (msg.type === 'port-ws-open') {
+      if (sockets.has(id)) return true;
+      try {
+        const params = new URLSearchParams(msg.query);
+        const host = params.get('host') || '127.0.0.1';
+        const port = Number(params.get('port'));
+        if ((!allowRemote && !isLoopbackHost(host)) || !Number.isInteger(port) || port < 1 || port > 65535) throw new Error('invalid target');
+        const url = new URL(`ws://${host.includes(':') ? `[${host}]` : host}:${port}`);
+        url.pathname = params.get('path') || '/';
+        url.search = params.get('q') || '';
+        const headers = {};
+        for (const name of ['Cookie', 'Origin', 'User-Agent']) {
+          if (typeof msg.headers?.[name] === 'string') headers[name] = msg.headers[name];
+        }
+        const ws = new WebSocket(url, msg.protocols || [], { headers, handshakeTimeout: 15000, maxPayload: MAX_FRAME, followRedirects: false });
+        const entry = { ws, timer: null };
+        sockets.set(id, entry);
+        ws.on('open', () => {
+          ws.pause();
+          entry.timer = setTimeout(() => ws.terminate(), 15000);
+          send({ type: 'port-ws-ready', tunnelId: id, protocol: ws.protocol });
+        });
+        ws.on('message', (data, binary) => {
+          send({ type: 'port-ws-msg', tunnelId: id, frameType: binary ? 2 : 1, data: data.toString('base64') });
+        });
+        ws.on('close', code => {
+          clearTimeout(entry.timer);
+          if (sockets.get(id) === entry) sockets.delete(id);
+          send({ type: 'port-ws-close', tunnelId: id, closeCode: validClose(code) ? code : 1011 });
+        });
+        ws.on('error', () => {
+          send({ type: 'port-ws-error', tunnelId: id });
+          ws.terminate();
+        });
+      } catch {
+        send({ type: 'port-ws-error', tunnelId: id });
+      }
+      return true;
+    }
+    const entry = sockets.get(id);
+    if (!entry) return true;
+    if (msg.type === 'port-ws-start') {
+      clearTimeout(entry.timer);
+      entry.ws.resume();
+    } else if (msg.type === 'port-ws-msg' && entry.ws.readyState === WebSocket.OPEN) {
+      if (![1, 2].includes(msg.frameType) || typeof msg.data !== 'string' || msg.data.length > MAX_FRAME * 4 / 3 + 4) {
+        entry.ws.terminate();
+      } else if (entry.ws.bufferedAmount > MAX_FRAME) {
+        entry.ws.close(1013, 'backpressure');
+      } else {
+        entry.ws.send(Buffer.from(msg.data, 'base64'), { binary: msg.frameType === 2 });
+      }
+    } else if (msg.type === 'port-ws-close') {
+      clearTimeout(entry.timer);
+      if (entry.ws.readyState === WebSocket.OPEN) entry.ws.close(validClose(msg.closeCode) ? msg.closeCode : 1000);
+      else entry.ws.terminate();
+    }
+    return true;
+  }
+  return {
+    handle,
+    closeAll() {
+      for (const { ws, timer } of sockets.values()) { clearTimeout(timer); ws.terminate(); }
+      sockets.clear();
+    },
+  };
+}

package/src/session-history.js

@@ -0,0 +1,31 @@
+/** Slice a loaded transcript for mobile/hub transfers. */
+
+export function parseHistoryQuery(query = {}) {
+  let tail = parseInt(query.tail ?? '0', 10);
+  if (Number.isNaN(tail) || tail < 0) tail = 0;
+  if (tail > 50_000) tail = 50_000;
+  let before = parseInt(query.before ?? '', 10);
+  if (Number.isNaN(before) || before < 0) before = null;
+  return { tail, before };
+}
+
+/**
+ * @param {unknown[]} messages
+ * @param {{ tail?: number, before?: number|null }} opts
+ */
+export function sliceHistoryMessages(messages, { tail = 0, before = null } = {}) {
+  const all = Array.isArray(messages) ? messages : [];
+  const total = all.length;
+  let end = total;
+  if (before != null) end = Math.min(before, total);
+  if (end < 0) end = 0;
+  let start = 0;
+  if (tail > 0 && end - start > tail) start = end - tail;
+  return {
+    messages: all.slice(start, end),
+    total,
+    truncated: start > 0,
+    oldestIndex: start,
+    tail: end - start,
+  };
+}