handmux 0.23.0 → 0.25.0

package/dist/src/workspaceProtocol.js

@@ -0,0 +1,158 @@
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RESTORE_REQUEST_FIELDS = new Set(['checkpointId', 'sessions']);
+const PROTECTION_STATUSES = ['protected', 'unprotected', 'degraded'];
+const PLAN_ACTIONS = ['create', 'create-renamed', 'already-present', 'unsupported'];
+const OPERATION_STATUSES = ['pending', 'running', 'succeeded', 'partial', 'failed', 'interrupted'];
+const RESULT_STATUSES = ['restored', 'already-present', 'failed'];
+const RESULT_STAGES = ['plan', 'topology', 'agent', 'restore', 'reconcile'];
+const recordOf = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value : null);
+const memberOf = (values, value) => (typeof value === 'string' && values.includes(value) ? value : undefined);
+const finiteNumber = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+const optionalString = (value) => (typeof value === 'string' ? value : value === null ? null : undefined);
+const stringArray = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === 'string') : []);
+const optionalField = (key, value) => (value === undefined ? {} : { [key]: value });
+export function isWorkspaceSafeId(value) {
+    return typeof value === 'string' && SAFE_ID.test(value) && value !== '.' && value !== '..';
+}
+export function parseWorkspaceRestoreRequest(value, defaultCheckpointId = 'latest') {
+    const request = recordOf(value);
+    if (!request || Object.keys(request).some((key) => !RESTORE_REQUEST_FIELDS.has(key)))
+        return null;
+    const checkpointId = request.checkpointId === undefined
+        ? defaultCheckpointId
+        : request.checkpointId;
+    if (!isWorkspaceSafeId(checkpointId))
+        return null;
+    const parsed = { checkpointId };
+    if (request.sessions !== undefined) {
+        if (!Array.isArray(request.sessions)
+            || request.sessions.some((name) => typeof name !== 'string' || !name || name.length > 256
+                || /[\x00-\x1f\x7f]/.test(name)))
+            return null;
+        parsed.sessions = [...request.sessions];
+    }
+    return parsed;
+}
+export function parseWorkspaceProtectionStatus(value) {
+    const status = recordOf(value);
+    if (!status)
+        return null;
+    return {
+        ...optionalField('status', memberOf(PROTECTION_STATUSES, status.status)),
+        ...optionalField('lastSuccessfulCaptureAt', optionalString(status.lastSuccessfulCaptureAt)),
+        ...optionalField('errorCode', optionalString(status.errorCode)),
+    };
+}
+export function parseWorkspaceRestoreStart(value) {
+    const start = recordOf(value);
+    if (!start)
+        return null;
+    return {
+        ...optionalField('operationId', typeof start.operationId === 'string' ? start.operationId : undefined),
+        ...optionalField('status', memberOf(OPERATION_STATUSES, start.status)),
+        ...optionalField('reused', typeof start.reused === 'boolean' ? start.reused : undefined),
+    };
+}
+const countsOf = (value) => {
+    const counts = recordOf(value);
+    if (!counts)
+        return undefined;
+    return {
+        ...optionalField('sessions', finiteNumber(counts.sessions)),
+        ...optionalField('windows', finiteNumber(counts.windows)),
+        ...optionalField('panes', finiteNumber(counts.panes)),
+        ...optionalField('agents', finiteNumber(counts.agents)),
+    };
+};
+const planSessionOf = (value) => {
+    const session = recordOf(value);
+    return session ? {
+        ...optionalField('logicalId', optionalString(session.logicalId)),
+        ...optionalField('sourceName', optionalString(session.sourceName)),
+        ...optionalField('targetName', optionalString(session.targetName)),
+        ...optionalField('action', session.action === null ? null : memberOf(PLAN_ACTIONS, session.action)),
+    } : null;
+};
+export function parseWorkspaceRecoveryPlan(value) {
+    const plan = recordOf(value);
+    if (!plan)
+        return null;
+    const rawPlanSummary = recordOf(plan.planSummary);
+    const summary = countsOf(plan.summary);
+    const planSummary = rawPlanSummary ? {
+        ...countsOf(rawPlanSummary),
+        ...optionalField('create', finiteNumber(rawPlanSummary.create)),
+        ...optionalField('renamed', finiteNumber(rawPlanSummary.renamed)),
+        ...optionalField('alreadyPresent', finiteNumber(rawPlanSummary.alreadyPresent)),
+        ...optionalField('unsupported', finiteNumber(rawPlanSummary.unsupported)),
+    } : undefined;
+    const pendingCount = finiteNumber(plan.pendingCount)
+        ?? (plan.pendingCount === null ? null : undefined);
+    return {
+        ...optionalField('checkpointId', optionalString(plan.checkpointId)),
+        ...optionalField('capturedAt', optionalString(plan.capturedAt)),
+        ...optionalField('changeReason', optionalString(plan.changeReason)),
+        ...optionalField('serverNow', optionalString(plan.serverNow)),
+        ...optionalField('expiresAt', optionalString(plan.expiresAt)),
+        ...optionalField('promptEligible', typeof plan.promptEligible === 'boolean' ? plan.promptEligible : undefined),
+        ...optionalField('resolved', typeof plan.resolved === 'boolean' ? plan.resolved : undefined),
+        ...optionalField('pendingCount', pendingCount),
+        ...optionalField('summary', summary),
+        ...optionalField('planSummary', planSummary),
+        ...(Array.isArray(plan.sessions) ? { sessions: plan.sessions.flatMap((session) => {
+                const parsed = planSessionOf(session);
+                return parsed ? [parsed] : [];
+            }) } : {}),
+        ...(Array.isArray(plan.warningCodes) ? { warningCodes: stringArray(plan.warningCodes) } : {}),
+        ...(plan.mapping !== undefined ? { mapping: plan.mapping } : {}),
+    };
+}
+export function parseWorkspaceRestoreOperation(value) {
+    const operation = recordOf(value);
+    if (!operation)
+        return null;
+    const progress = recordOf(operation.progress);
+    const request = recordOf(operation.request);
+    const results = Array.isArray(operation.results)
+        ? operation.results.flatMap((candidate) => {
+            const result = recordOf(candidate);
+            const session = planSessionOf(candidate);
+            if (!result || !session)
+                return [];
+            return [{
+                    ...session,
+                    ...optionalField('status', result.status === null ? null : memberOf(RESULT_STATUSES, result.status)),
+                    ...optionalField('stage', result.stage === null ? null : memberOf(RESULT_STAGES, result.stage)),
+                    ...optionalField('errorCode', optionalString(result.errorCode)),
+                    ...optionalField('errorMessage', optionalString(result.errorMessage)),
+                    warningCodes: stringArray(result.warningCodes),
+                }];
+        }) : [];
+    const parsedProgress = progress ? {
+        ...optionalField('completed', finiteNumber(progress.completed)),
+        ...optionalField('total', finiteNumber(progress.total)),
+    } : undefined;
+    const checkpointId = typeof request?.checkpointId === 'string' ? request.checkpointId : undefined;
+    const parsedRequest = request && checkpointId ? {
+        checkpointId,
+        ...(Array.isArray(request.sessions) ? { sessions: stringArray(request.sessions) } : {}),
+        ...(typeof request.historical === 'boolean' ? { historical: request.historical } : {}),
+    } : undefined;
+    return {
+        ...(typeof operation.id === 'string' ? { id: operation.id } : {}),
+        ...optionalField('status', operation.status === null ? null : memberOf(OPERATION_STATUSES, operation.status)),
+        ...optionalField('request', parsedRequest),
+        ...optionalField('createdAt', optionalString(operation.createdAt)),
+        ...optionalField('updatedAt', optionalString(operation.updatedAt)),
+        ...optionalField('startedAt', optionalString(operation.startedAt)),
+        ...optionalField('completedAt', optionalString(operation.completedAt)),
+        ...optionalField('progress', parsedProgress),
+        ...optionalField('summary', countsOf(operation.summary)),
+        ...(Array.isArray(operation.results) ? { results } : {}),
+        ...optionalField('errorCode', optionalString(operation.errorCode)),
+        ...optionalField('errorMessage', optionalString(operation.errorMessage)),
+        ...(Array.isArray(operation.warningCodes) ? { warningCodes: stringArray(operation.warningCodes) } : {}),
+        ...(operation.mapping !== undefined ? { mapping: operation.mapping } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -22,27 +22,32 @@
     "pwa"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.16.0"
   },
   "bin": {
     "handmux": "bin/handmux.js"
   },
   "files": [
-    "bin",
-    "src",
-    "hooks",
-    "public",
-    "README.zh-CN.md"
+    "bin/handmux.js",
+    "bin/node-version.js",
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
   ],
   "scripts": {
-    "start": "node bin/handmux.js start",
-    "dev": "node bin/handmux.js start --foreground",
-    "handmux": "node bin/handmux.js",
+    "start": "npm run build:server && node dist/bin/handmux.js start",
+    "dev": "npm run build:server && node dist/bin/handmux.js start --foreground",
+    "handmux": "npm run build:server && node dist/bin/handmux.js",
+    "build:server": "node scripts/build-server.mjs",
     "bundle": "node scripts/bundle-web.mjs",
-    "prepack": "node scripts/bundle-web.mjs",
-    "test": "vitest run",
-    "test:workspace-host": "HANDMUX_WORKSPACE_HOST=1 vitest run test/workspaceHost.test.js",
-    "test:workspace-docker": "HANDMUX_WORKSPACE_DOCKER=1 vitest run test/workspaceDocker.test.js"
+    "prepack": "npm run bundle && npm run build:server",
+    "typecheck:source": "node scripts/check-typescript-product-source.mjs",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "npm run build:server && vitest run",
+    "test:pack": "node scripts/pack-smoke.mjs",
+    "test:workspace-host": "npm run build:server && HANDMUX_WORKSPACE_HOST=1 vitest run test/workspaceHost.test.js",
+    "test:workspace-docker": "npm run build:server && HANDMUX_WORKSPACE_DOCKER=1 vitest run test/workspaceDocker.test.js"
   },
   "dependencies": {
     "@clack/prompts": "0.11.0",
@@ -58,17 +63,25 @@
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {
+    "@types/busboy": "^1.5.4",
+    "@types/compression": "^1.8.1",
+    "@types/express": "4.17.25",
+    "@types/node": "22.20.1",
+    "@types/supertest": "7.2.1",
+    "@types/web-push": "^3.6.4",
+    "@types/ws": "^8.18.1",
     "supertest": "^7.0.0",
+    "typescript": "6.0.3",
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {"version":"0.25.0","date":"2026-09-01","zh":"Pi 原生接入 · 多 Agent 对话更可靠","en":"Native Pi support · more reliable agent chat"},
+    {"version":"0.24.0","date":"2026-08-11","zh":"Codex 任务进度与 Goal 原生上线","en":"Native Codex task progress and Goals"},
     {"version":"0.23.0","date":"2026-08-09","zh":"Codex 托管对话正式上线","en":"Managed Codex chat is here"},
     {"version":"0.22.1","date":"2026-08-04","zh":"网页宽度与网站版本分开控制","en":"Separate page width and site-version controls"},
     {"version":"0.22.0","date":"2026-08-03","zh":"全屏设置 · 窗口与分屏管理更清晰","en":"Full-screen Settings · clearer window and pane management"},
     {"version":"0.21.0","date":"2026-08-03","zh":"网页预览：手机直连、电脑代理与静态目录","en":"Web preview: direct, computer proxy, and static folders"},
     {"version":"0.20.3","date":"2026-08-01","zh":"实时终端显示更稳定流畅","en":"More stable, smoother live terminals"},
-    {"version":"0.20.2","date":"2026-07-27","zh":"实时终端长时间运行更流畅","en":"Smoother long-running live terminals"},
-    {"version":"0.20.1","date":"2026-07-26","zh":"聊天发送修复 · 电脑键盘不中断","en":"Reliable chat sending · uninterrupted desktop input"},
-    {"version":"0.20.0","date":"2026-07-26","zh":"终端实时推送 · 弱网自动回退","en":"Live terminal pushing · automatic network fallback"}
+    {"version":"0.20.2","date":"2026-07-27","zh":"实时终端长时间运行更流畅","en":"Smoother long-running live terminals"}
   ]
 }

package/hooks/handmux-notify.sh

@@ -1,22 +0,0 @@
-#!/bin/sh
-# handmux 上报 hook. $1 = stop | notify | prompt | end | resume | permreq | compacting | compact | stopfail.
-# (compacting/compact/stopfail 是版本门控事件:PreCompact/PostCompact/StopFailure，只在够新的 Claude 上注册。)
-# stdin = Claude Code 原始 payload(JSON).
-# (resume  = PostToolUse on AskUserQuestion/ExitPlanMode:答完选项/批准计划 → 状态翻回进行中、带所选项。)
-# (permreq = PermissionRequest:真实弹框一出现就发、带 tool_name → 比 permission_prompt 早亮「需要你」。)
-# 只做一件事:把本次事件写进一个本地 JSON 状态文件(键=tmux pane,值=该 pane 最新事件)。不联网、
-# 不依赖服务进程是否在跑 → 永不阻塞 Claude(始终 exit 0)。服务端按需读这个文件(见 claudeEvents.js)。
-# 真正的读-改-写交给同目录的 handmux-write.js(node:真 JSON 解析 + 文件锁,多 pane 并发 hook 不丢更新)。
-CFG="$(dirname "$0")/handmux-notify.env"
-[ -f "$CFG" ] && . "$CFG"
-PANE="${CLAUDE_PANE:-$TMUX_PANE}"
-[ -z "$PANE" ] && exit 0   # 不在 tmux 里(没有 pane 可定位)→ 暂不记录
-FILE="${HANDMUX_STATE:-$HOME/.claude/handmux-state.json}"
-# 毫秒时间戳:与旧实现的 Date.now() 同单位(客户端已阅水位线兼容)。优先 perl,退化到 秒×1000。
-TS=$(perl -MTime::HiRes -e 'printf "%.0f", Time::HiRes::time()*1000' 2>/dev/null)
-[ -z "$TS" ] && TS=$(( $(date +%s) * 1000 ))
-HOST=$(hostname 2>/dev/null || printf '')
-# payload 经 stdin 原样流给 node(不在 shell 里转义,避免坏数据);pane 含 '%' 直接进 JSON 字段,
-# 不再进 URL → 彻底告别旧的 "%110 被 url-decode 丢弃" 那类坑。
-node "$(dirname "$0")/handmux-write.cjs" "$FILE" "$PANE" "$1" "$TS" "$HOST" 2>/dev/null || true
-exit 0

package/hooks/handmux-write.cjs

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-// handmux hook writer. Updates ONE JSON state file keyed by tmux pane id with this pane's latest
-// Claude event:  { "%pane": { ts, src, host, payload }, ... }.  Invoked by handmux-notify.sh:
-//   node handmux-write.cjs <file> <pane> <src> <ts> <host>     (stdin = Claude's raw hook payload JSON)
-//
-// .cjs (not .js): runs standalone via `node <file>`, including from ~/.claude/hooks (no package.json) —
-// .cjs forces CommonJS everywhere; a bare .js under the server tree ("type":"module") would be ESM and
-// break require().
-//
-// Why node (not pure shell): the file is a single JSON object, so each event is a read-modify-write that
-// must parse JSON and not clobber other panes — shell can't do that safely. The user runs many Claude
-// panes at once, so hooks fire concurrently: we take a short O_EXCL lock (stealing a stale one) around
-// the read-modify-write and replace atomically (tmp + rename), so concurrent writers don't lose updates
-// or corrupt the file. Best-effort throughout and silent — the hook is fire-and-forget and must never
-// fail Claude (the shell wrapper swallows errors and always exits 0).
-const fs = require('node:fs');
-
-const [, , file, pane, src, ts, host = ''] = process.argv;
-if (!file || !pane || !src) process.exit(0);
-
-let payload = {};
-try { payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { /* unreadable stdin → {} */ }
-
-// idle_prompt ("been idle ~60s") is decided in update() against the pane's PRIOR state: it either trails
-// a resting state (done/needs → drop, so it can't bump ts and re-surface an already-cleared 已完成) or it
-// terminates an ESC-interrupted working turn (→ clear the stuck 进行中). Flag it here; the read-modify-
-// write under the lock — the only place we can read the prior state safely — makes the call.
-const isIdle = src === 'notify' && payload && payload.notification_type === 'idle_prompt';
-
-// Synchronous nap without busy-spinning (the hook runs async, so a few ms is free). SharedArrayBuffer
-// may be unavailable in odd runtimes — fall back to a tiny busy loop so the lock retry still paces.
-const nap = (ms) => {
-  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
-  catch { const end = Date.now() + ms; while (Date.now() < end) { /* spin */ } }
-};
-
-try { fs.mkdirSync(path.dirname(file), { recursive: true }); } catch { /* ignore */ }
-
-function update() {
-  let obj = {};
-  try { const j = JSON.parse(fs.readFileSync(file, 'utf8')); if (j && typeof j === 'object' && !Array.isArray(j)) obj = j; }
-  catch { /* fresh / corrupt / half-written → start clean */ }
-  const prevSrc = obj[pane] && obj[pane].src;
-  if (isIdle) {
-    // idle after a resting state (done/needs/nothing) is just the "still waiting" reminder → drop and
-    // leave the file as it was (recording it would bump ts and re-surface an already-cleared 已完成).
-    // idle after a WORKING turn (prompt/resume) that never got a Stop = an ESC interrupt / walk-away —
-    // no Stop hook fires there, so idle is the only signal the turn ended. Without this the pane would
-    // stay latched at 进行中 forever; treat it as a soft end and clear the pane.
-    if (prevSrc === 'prompt' || prevSrc === 'resume') { delete obj[pane]; }
-    else return;                                             // resting → drop without writing
-  } else if (src === 'end') {
-    // SessionEnd drops the pane on a clean exit. But /clear (and /resume) END the old session AND START a
-    // new one — SessionEnd(old) + SessionStart(new) fire as two async hooks, in either order. A late end for
-    // the OLD session must NOT wipe the NEW session's binding: only drop when what we currently hold IS the
-    // ending session (or neither side carries a session_id to compare — preserve the plain clean-exit drop).
-    const curSid = obj[pane] && obj[pane].payload && obj[pane].payload.session_id;
-    const endSid = payload && payload.session_id;
-    if (!curSid || !endSid || curSid === endSid) delete obj[pane];
-  } else {
-    obj[pane] = { ts: Number(ts) || 0, src, host, payload };
-  }
-  const tmp = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(obj));
-  fs.renameSync(tmp, file);                                   // atomic: a torn write can't corrupt the file
-}
-
-const lock = `${file}.lock`;
-let held = false;
-for (let i = 0; i < 60 && !held; i++) {                       // ~0.9s budget, then write lockless (best-effort)
-  try { fs.closeSync(fs.openSync(lock, 'wx')); held = true; } // O_EXCL → atomic "I hold it"
-  catch {
-    try { if (Date.now() - fs.statSync(lock).mtimeMs > 3000) fs.unlinkSync(lock); } catch { /* steal a stale lock */ }
-    nap(15);
-  }
-}
-try { update(); } catch { /* best effort */ }
-if (held) { try { fs.unlinkSync(lock); } catch { /* ignore */ } }