handmux 0.23.0 → 0.24.0

package/dist/src/agents/scanUtils.js

@@ -0,0 +1,262 @@
+// Agent-agnostic scan/parse helpers shared by every agent driver and the orphan engine. This is the LEAF
+// layer: it imports nothing from the agent registry, so drivers (claude.js / codex.js) and the engine
+// (orphans.js) can all depend on it without an import cycle.
+//
+// Everything here is about turning `ps`/`tmux`/`lsof` output and session jsonl files into structured data;
+// none of it knows which coding agent it's looking at — the per-agent specifics (which process name, where
+// sessions live, how to resume) live in the driver descriptors that USE these helpers.
+import { execFile } from 'node:child_process';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { parseTmuxRows } from '../tmux/format.js';
+const isRecord = (value) => value !== null && typeof value === 'object';
+// Tolerant promisified execFile: resolves '' on any error (no server, missing binary, non-zero exit).
+// Detection is best-effort and must never throw the whole request.
+export function defaultRun(cmd, args) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+            resolve(err ? '' : String(stdout));
+        });
+    });
+}
+// A coding-agent session id is a UUID (Claude's jsonl filename; Codex's rollout-file trailing id). Validate
+// strictly: takeover types `<bin> resume <id>` into a shell via send-keys, so a non-UUID id would be a
+// shell-injection vector.
+export const isSessionUuid = (value) => typeof value === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+// Strip /dev/ and fold "no controlling terminal" markers (macOS '??', Linux '?') to '' so ps ttys and
+// tmux pane_ttys compare equal: ps 'ttys010' / tmux '/dev/ttys010' → 'ttys010'; ps 'pts/3' / tmux
+// '/dev/pts/3' → 'pts/3'.
+export function normTty(value) {
+    const s = String(value || '').trim();
+    if (!s || s === '??' || s === '?' || s === '-')
+        return '';
+    return s.replace(/^\/dev\//, '');
+}
+// ps `etime` (elapsed since start) → milliseconds. Formats (macOS + Linux, no spaces): "MM:SS",
+// "HH:MM:SS", "DD-HH:MM:SS". Used only to derive a startedAt for display/recognition (the "A加成"),
+// NOT for session attribution — a resumed session's process starts long after its jsonl's first event.
+export function etimeToMs(etime) {
+    const s = String(etime).trim();
+    if (!s)
+        return 0;
+    let days = 0;
+    let rest = s;
+    const dash = s.indexOf('-');
+    if (dash >= 0) {
+        days = Number(s.slice(0, dash)) || 0;
+        rest = s.slice(dash + 1);
+    }
+    let sec = 0;
+    for (const p of rest.split(':'))
+        sec = sec * 60 + (Number(p) || 0);
+    return (days * 86400 + sec) * 1000;
+}
+// Parse `ps -Ao pid=,ppid=,stat=,etime=,tty=,args=` → LIVE agent processes only, each tagged with the id of
+// the FIRST driver whose `procMatch` regex matches its argv. `agents` is the driver list; a proc matching
+// none is dropped. args (last column) may contain spaces; etime has none. STOPPED (STAT 'T', a Ctrl-Z-
+// suspended job-control stack — verified real: one terminal can hold 8 suspended `claude`s) and ZOMBIE
+// ('Z') processes are dropped: they aren't active sessions to steer, and a suspended original can't write
+// its jsonl so there's nothing to race.
+export function parseAgentProcs(psOut, agents) {
+    const out = [];
+    for (const line of String(psOut).split('\n')) {
+        const m = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const [, pid, ppid, stat, etime, tty, rawArgs] = m;
+        if (!pid || !ppid || !stat || !etime || !tty || rawArgs === undefined)
+            continue;
+        if (stat.startsWith('T') || stat.startsWith('Z'))
+            continue;
+        const args = rawArgs.trim();
+        const agent = agents.find((a) => a.procMatch.test(args));
+        if (!agent)
+            continue;
+        out.push({ pid: Number(pid), ppid: Number(ppid), etimeMs: etimeToMs(etime), tty: normTty(tty), args, agent: agent.id });
+    }
+    return out;
+}
+// Parse q-escaped `tmux list-panes` rows → the set of pane ttys and pane (shell) pids.
+export function parsePaneMembership(tmuxOut) {
+    const ttys = new Set();
+    const pids = new Set();
+    for (const [tty, pid] of parseTmuxRows(tmuxOut, 2, 'pane membership')) {
+        const nt = normTty(tty);
+        if (nt)
+            ttys.add(nt);
+        const n = Number(pid);
+        if (n)
+            pids.add(n);
+    }
+    return { ttys, pids };
+}
+// Orphan = an agent proc WITH a real controlling tty that is neither one of tmux's pane ttys nor a child of
+// a pane's shell. The tty requirement drops background/headless runs (SDK/`-p`/`exec` piped, tty '') —
+// those aren't interactive sessions a user would "take over".
+export function findOrphans(procs, membership) {
+    return procs.filter((p) => p.tty && !membership.ttys.has(p.tty) && !membership.pids.has(p.ppid));
+}
+// A real cwd → its ~/.claude/projects directory name. Claude replaces every non-alphanumeric char with
+// '-' (verified: '/home/user/handmux' → '-home-user-handmux'; both '/'
+// and '_' fold to '-'). The mapping is LOSSY (not reversible), so we only ever encode forward, then
+// confirm each candidate jsonl's recorded `cwd` matches before trusting it.
+export function encodeProjectDir(cwd) {
+    return String(cwd).replace(/[^A-Za-z0-9]/g, '-');
+}
+// Read the last `bytes` of a file (for the trailing conversation). The first line of the chunk may be
+// truncated mid-JSON — callers skip lines that don't parse.
+export async function readTail(file, bytes = 65536) {
+    const fh = await fsp.open(file, 'r');
+    try {
+        const { size } = await fh.stat();
+        const start = Math.max(0, size - bytes);
+        const len = size - start;
+        if (len <= 0)
+            return '';
+        const buf = Buffer.alloc(len);
+        await fh.read(buf, 0, len, start);
+        return buf.toString('utf8');
+    }
+    finally {
+        await fh.close();
+    }
+}
+// Read the first `bytes` of a file (the session header carries `cwd` early).
+export async function readHead(file, bytes = 65536) {
+    const fh = await fsp.open(file, 'r');
+    try {
+        const buf = Buffer.alloc(bytes);
+        const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+        return buf.slice(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await fh.close();
+    }
+}
+// First `"cwd":"..."` anywhere in a chunk (both Claude and Codex record the session cwd early in the file).
+export function firstCwd(headText) {
+    const m = String(headText).match(/"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+    const encoded = m?.[1];
+    if (encoded === undefined)
+        return '';
+    try {
+        const parsed = JSON.parse(`"${encoded}"`);
+        return typeof parsed === 'string' ? parsed : encoded;
+    }
+    catch {
+        return encoded;
+    }
+}
+// Pull the last user-typed message text out of a Claude jsonl tail, for a recognizable one-line label.
+// Entries are line-delimited JSON; conversational turns are type 'user' with message.role 'user', whose
+// content is either a string or an array of blocks ({type:'text',text}). Meta rows (last-prompt/ai-title/
+// mode/attachment/summary) are ignored. Scans newest-first.
+export function lastUserSnippet(tailText, max = 80) {
+    const rows = String(tailText).split('\n');
+    for (let i = rows.length - 1; i >= 0; i--) {
+        const line = rows[i]?.trim() ?? '';
+        if (!line || line[0] !== '{')
+            continue;
+        let data;
+        try {
+            data = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(data) || data.type !== 'user' || !isRecord(data.message) || data.message.role !== 'user')
+            continue;
+        const c = data.message.content;
+        let text = '';
+        if (typeof c === 'string')
+            text = c;
+        else if (Array.isArray(c))
+            text = c
+                .filter((block) => isRecord(block) && block.type === 'text')
+                .map((block) => typeof block.text === 'string' ? block.text : '')
+                .join(' ');
+        text = text.replace(/\s+/g, ' ').trim();
+        if (text)
+            return text.length > max ? `${text.slice(0, max)}…` : text;
+    }
+    return '';
+}
+// Resolve a cwd to the newest jsonl in its ENCODED project dir whose recorded cwd matches (guards against
+// the lossy encoding colliding two real paths). This is Claude's layout (~/.claude/projects/<enc-cwd>/
+// <uuid>.jsonl); Codex has its own resolver. `snippet` extracts the last user turn (parser injected so
+// each agent's jsonl shape is handled). Returns sessionId, a busy/idle guess (mtime recency), the snippet,
+// and the last-activity timestamp; {} when the dir is absent or nothing matches.
+export async function resolveEncodedDirSession(projectsDir, cwd, { busyMs = 8000, now = Date.now, snippet = lastUserSnippet } = {}) {
+    const dir = path.join(projectsDir, encodeProjectDir(cwd));
+    let names;
+    try {
+        names = (await fsp.readdir(dir)).filter((n) => n.endsWith('.jsonl'));
+    }
+    catch {
+        return {};
+    }
+    const stats = [];
+    for (const n of names) {
+        try {
+            stats.push({ n, mtime: (await fsp.stat(path.join(dir, n))).mtimeMs });
+        }
+        catch { /* gone */ }
+    }
+    stats.sort((a, b) => b.mtime - a.mtime);
+    for (const { n, mtime } of stats) {
+        const file = path.join(dir, n);
+        let head;
+        try {
+            head = await readHead(file);
+        }
+        catch {
+            continue;
+        }
+        if (firstCwd(head) !== cwd)
+            continue; // different real path collided onto the same dir → skip
+        let snip = '';
+        try {
+            snip = snippet(await readTail(file));
+        }
+        catch { /* best effort */ }
+        return {
+            sessionId: n.replace(/\.jsonl$/, ''),
+            state: now() - mtime < busyMs ? 'busy' : 'idle',
+            snippet: snip,
+            lastActivity: Math.round(mtime),
+        };
+    }
+    return {};
+}
+// A tmux session name derived from a cwd basename, kept within isValidSessionName ([A-Za-z0-9-], ≤16):
+// `<prefix>-<alnum label, ≤8>-<n>`. n disambiguates against existing sessions.
+export function takeoverSessionName(cwdLabel, n, prefix = 'cc') {
+    const base = String(cwdLabel || '').replace(/[^A-Za-z0-9]/g, '').slice(0, 8) || prefix;
+    return `${prefix}-${base}-${n}`.slice(0, 16);
+}
+// Coerce a user-typed takeover name into a valid tmux session name (isValidSessionName: [A-Za-z0-9-], ≤16):
+// non-alnum runs → a single '-', trimmed of edge hyphens, capped at 16. Returns '' if nothing usable is
+// left (caller then falls back to the generated name).
+export function sanitizeSessionName(s) {
+    return String(s || '').replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 16).replace(/-+$/, '');
+}
+// First name in `<base>, base-2, base-3, …` (each capped at 16) that isn't already taken. null if none free.
+export function freeSessionName(base, taken) {
+    if (!taken.has(base))
+        return base;
+    for (let i = 2; i < 1000; i++) {
+        const cand = `${base}-${i}`.slice(0, 16);
+        if (!taken.has(cand))
+            return cand;
+    }
+    return null;
+}
+export const isShell = (command) => /^-?(zsh|bash|sh|fish|dash|tcsh|csh|ksh)$/.test(String(command || ''));
+export async function lsofCwd(run, pid) {
+    const out = await run('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn']);
+    for (const line of out.split('\n'))
+        if (line[0] === 'n')
+            return line.slice(1).trim();
+    return '';
+}

package/dist/src/apiErrors.js

@@ -0,0 +1,77 @@
+import { randomUUID } from 'node:crypto';
+export class PublicApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'PublicApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+function requestIdFor(locals, idFactory) {
+    if (typeof locals.requestId === 'string' && locals.requestId)
+        return locals.requestId;
+    const requestId = idFactory();
+    locals.requestId = requestId;
+    return requestId;
+}
+function errorFields(error) {
+    if (!(error instanceof Error))
+        return { value: String(error) };
+    return { name: error.name, message: error.message, stack: error.stack };
+}
+function isInvalidJson(error) {
+    if (!(error instanceof SyntaxError) || !error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return candidate.status === 400 && candidate.type === 'entity.parse.failed';
+}
+export function apiRequestContext({ idFactory = randomUUID } = {}) {
+    return (_req, res, next) => {
+        const requestId = requestIdFor(res.locals, idFactory);
+        res.setHeader('X-Request-Id', requestId);
+        next();
+    };
+}
+export function apiNotFound({ idFactory = randomUUID } = {}) {
+    return (_req, res) => {
+        const requestId = requestIdFor(res.locals, idFactory);
+        res.setHeader('X-Request-Id', requestId);
+        const body = { error: 'not found', code: 'not_found', requestId };
+        res.status(404).json(body);
+    };
+}
+export function apiErrorBoundary({ idFactory = randomUUID, log = console, } = {}) {
+    return (error, req, res, next) => {
+        if (res.headersSent) {
+            next(error);
+            return;
+        }
+        const requestId = requestIdFor(res.locals, idFactory);
+        res.setHeader('X-Request-Id', requestId);
+        let status = 500;
+        let code = 'internal_error';
+        let message = 'internal server error';
+        if (error instanceof PublicApiError) {
+            status = error.status;
+            code = error.code;
+            message = error.message;
+        }
+        else if (isInvalidJson(error)) {
+            status = 400;
+            code = 'invalid_json';
+            message = 'invalid json';
+        }
+        if (status >= 500) {
+            log.error('[handmux] api error', {
+                requestId,
+                method: req.method,
+                path: req.originalUrl,
+                error: errorFields(error),
+            });
+        }
+        const body = { error: message, code, requestId };
+        res.status(status).json(body);
+    };
+}

package/{src → dist/src}/appName.js

@@ -1,23 +1,22 @@
 // Runtime app-name injection. The web bundle ships prebuilt, so a user's custom name (set at
 // `handmux start --name`) can't be baked at build time — instead the server rewrites the name into
 // the shell HTML and the PWA manifest as it serves them. Pure string/object transforms so they're
-// unit-testable; the server side-effects (read file / send) live in server.js.
-
-const escAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;')
-  .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-
+// unit-testable; the server side-effects (read file / send) live in server.ts.
+const escAttr = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 // Replace the browser-tab title and the iOS home-screen label in index.html. Matches by tag/attr,
 // not by the default text, so it survives a changed default. No-op when a tag is absent.
 export function applyAppName(html, name) {
-  if (!name) return html;
-  const e = escAttr(name);
-  return html
-    .replace(/<title>[^<]*<\/title>/, `<title>${e}</title>`)
-    .replace(/(<meta name="apple-mobile-web-app-title" content=")[^"]*(")/, `$1${e}$2`);
+    if (!name)
+        return html;
+    const e = escAttr(name);
+    return html
+        .replace(/<title>[^<]*<\/title>/, `<title>${e}</title>`)
+        .replace(/(<meta name="apple-mobile-web-app-title" content=")[^"]*(")/, `$1${e}$2`);
 }
-
 // Override the PWA install name (Android uses short_name; both set so home-screen + app list agree).
 export function applyManifestName(manifest, name) {
-  if (!name) return manifest;
-  return { ...manifest, name, short_name: name };
+    if (!name)
+        return manifest;
+    return { ...manifest, name, short_name: name };
 }

package/dist/src/asr/iflyConfig.js

@@ -0,0 +1,7 @@
+export function asrConfig(env = process.env) {
+    return { appId: env.XFYUN_APPID || '', apiKey: env.XFYUN_APIKEY || '', apiSecret: env.XFYUN_APISECRET || '' };
+}
+export function isAsrConfigured(env = process.env) {
+    const c = asrConfig(env);
+    return !!(c.appId && c.apiKey && c.apiSecret);
+}

package/dist/src/asr/iflySign.js

@@ -0,0 +1,14 @@
+import { createHmac } from 'node:crypto';
+// Build a fully-signed iFlytek IAT v2 WebSocket URL. The secret (apiSecret) is used only here on the
+// server — the browser receives only the resulting URL (HMAC output, not the key). `host`/`date` are
+// injectable so this is deterministic and unit-testable; production passes host='iat-api.xfyun.cn'
+// and date=new Date().toUTCString() (RFC1123 GMT, iFlytek allows ±300s skew).
+export function buildIatSignedUrl({ appId, apiKey, apiSecret, host = 'iat-api.xfyun.cn', date, }) {
+    const requestLine = 'GET /v2/iat HTTP/1.1';
+    const signatureOrigin = `host: ${host}\ndate: ${date}\n${requestLine}`;
+    const signature = createHmac('sha256', apiSecret).update(signatureOrigin).digest('base64');
+    const authorizationOrigin = `api_key="${apiKey}", algorithm="hmac-sha256", headers="host date request-line", signature="${signature}"`;
+    const authorization = Buffer.from(authorizationOrigin, 'utf8').toString('base64');
+    const qs = new URLSearchParams({ authorization, date, host });
+    return { url: `wss://${host}/v2/iat?${qs.toString()}`, appId };
+}

package/dist/src/auth.js

@@ -0,0 +1,27 @@
+import crypto from 'node:crypto';
+export function loadToken(env = process.env) {
+    let token = env.HANDMUX_TOKEN;
+    if (!token) {
+        token = crypto.randomBytes(24).toString('base64url');
+        console.log(`[handmux] no HANDMUX_TOKEN set; generated token: ${token}`);
+    }
+    return token;
+}
+const sha = (value) => crypto.createHash('sha256').update(String(value)).digest();
+export function tokenEquals(a, b) {
+    return crypto.timingSafeEqual(sha(a), sha(b));
+}
+export function bearerFrom(header) {
+    if (!header)
+        return null;
+    const m = /^Bearer (.+)$/.exec(header);
+    return m?.[1] ?? null;
+}
+export function expressAuth(token) {
+    return (req, res, next) => {
+        const provided = bearerFrom(req.get('authorization'));
+        if (provided && tokenEquals(provided, token))
+            return next();
+        res.status(401).json({ error: 'unauthorized' });
+    };
+}

package/dist/src/browser/bootstrap.js

@@ -0,0 +1,72 @@
+import { randomBytes } from 'node:crypto';
+const BOOTSTRAP_PREFIX = '/_browser-bootstrap/';
+function normalizedOrigin(raw) {
+    const url = new URL(raw);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new Error('browser bootstrap origin must use http or https');
+    return url.origin;
+}
+export function isBrowserBootstrapPath(pathname) {
+    return String(pathname || '').startsWith(BOOTSTRAP_PREFIX);
+}
+export function createBrowserBootstrapStore({ randomToken = () => randomBytes(24).toString('base64url'), now = Date.now, ttlMs = 60_000, } = {}) {
+    const tickets = new Map();
+    const prune = () => {
+        const current = now();
+        for (const [token, entry] of tickets)
+            if (entry.expiresAt <= current)
+                tickets.delete(token);
+    };
+    return {
+        issue({ url, origin, deviceId, preserveMethod = false, redirectStatus = 302, }) {
+            prune();
+            const expectedOrigin = normalizedOrigin(origin);
+            const target = new URL(url);
+            if (target.origin !== expectedOrigin || !target.pathname.split('/')[1]?.startsWith('_browser-')) {
+                throw new Error('browser bootstrap target must be a session on its public origin');
+            }
+            const token = randomToken();
+            tickets.set(token, {
+                url: target.toString(),
+                origin: expectedOrigin,
+                deviceId,
+                preserveMethod,
+                redirectStatus,
+                expiresAt: now() + ttlMs,
+            });
+            return new URL(`${BOOTSTRAP_PREFIX}${encodeURIComponent(token)}`, expectedOrigin).toString();
+        },
+        consume(pathname, origin) {
+            prune();
+            if (!isBrowserBootstrapPath(pathname))
+                return null;
+            let token;
+            try {
+                token = decodeURIComponent(String(pathname).slice(BOOTSTRAP_PREFIX.length));
+            }
+            catch {
+                return null;
+            }
+            const entry = tickets.get(token);
+            let requestedOrigin;
+            try {
+                requestedOrigin = normalizedOrigin(origin);
+            }
+            catch {
+                return null;
+            }
+            if (!entry || entry.origin !== requestedOrigin)
+                return null;
+            tickets.delete(token);
+            if (entry.preserveMethod) {
+                return {
+                    url: entry.url,
+                    deviceId: entry.deviceId,
+                    preserveMethod: true,
+                    redirectStatus: entry.redirectStatus,
+                };
+            }
+            return { url: entry.url, deviceId: entry.deviceId };
+        },
+    };
+}