@cjhyy/code-shell-server 0.9.8 → 0.9.10

package/README.md

@@ -1,6 +1,8 @@
 # @cjhyy/code-shell-server
 
-CodeShell 服务端传输层（纯 Node、零 Electron）：mobile remote 的 HTTP/WS host、配对、passcode 门、tunnel、rooms、上传，以及 **headless 无账号 Web host（`code-shell-serve`）**。
+CodeShell 服务端传输与管理服务（纯 Node、零 Electron）：mobile remote 的 HTTP/WS host、配对、passcode 门、tunnel、rooms、上传，供 Desktop Web 与 Hub 共用的配置/会话/文件/Link 服务，以及 **个人 Hub Web host（`code-shell-serve`）**。
+
+完整的原生 Node.js 安装、模型配置、管理员初始化、systemd 后台运行、HTTPS 和备份步骤见 [服务端部署指南](../../docs/deployment.md)。
 
 ## 聚焦入口
 
@@ -12,6 +14,8 @@ CodeShell 服务端传输层（纯 Node、零 Electron）：mobile remote 的 HT
 | `@cjhyy/code-shell-server/worker`        | 与传输无关的 stdio worker 生命周期和行协议桥接                    |
 | `@cjhyy/code-shell-server/mobile-remote` | 配对、访问门禁、rooms、上传、LAN/tunnel host 和移动端协议类型     |
 | `@cjhyy/code-shell-server/serve`         | Headless HTTP/WebSocket host 与 `code-shell-serve` CLI 组合默认值 |
+| `@cjhyy/code-shell-server/desktop-web`   | 设备配对换 Cookie、已知 Workspace 校验与共享管理 HTTP API         |
+| `@cjhyy/code-shell-server/links`         | Link 目录、连接管理、设备授权及受限 HTTP handler                  |
 
 ```ts
 import { listDiskSessions } from "@cjhyy/code-shell-server/storage";
@@ -19,7 +23,8 @@ import { RemoteHostManager } from "@cjhyy/code-shell-server/mobile-remote";
 import { WorkerBridgeCore } from "@cjhyy/code-shell-server/worker";
 ```
 
-包根入口仍是四个入口的兼容并集。新消费方应避免根入口，以免只使用 storage
+包根入口保留 storage、worker、mobile-remote、serve 和 desktop-web 的兼容导出；
+Link 使用独立 `/links` 入口。新消费方应避免根入口，以免只使用 storage
 或 transport 时也求值无关的宿主组合。
 
 `/storage`、`/worker` 和 `/mobile-remote` 没有 Coding/Web 静态导入。外部
@@ -27,52 +32,109 @@ Agent 策略由产品宿主通过 `ResidentAgentOptions.appendSystemPrompt` 注
 `/serve` 则是有意保留的开箱即用产品入口：CLI 被调用时解析 Coding stdio
 worker 和已构建的 Web app。
 
-## code-shell-serve — 无账号 Web host
+## 两种宿主，共用浏览器工作台
+
+`packages/web/app/Workbench.tsx` 组合对话、模型、Skills、MCP、历史、文件及 Link 页面。
+Hub 的 `App` / `useHubController` 提供管理员认证后的状态与操作；Desktop 的
+`DesktopApp` 使用原有 `useRemoteApp` 和设备协议，驱动原来的 Desktop Worker。
+Desktop Web 不会创建第二个 Hub Worker，也不需要再建 Hub 管理员。
+
+`createDesktopWebApi` 将配对设备换成短期 HttpOnly Cookie，用于同一套受限 HTTP
+管理服务。宿主注入已知 Workspace 解析、运行门禁和热更新回调；业务服务复用
+`hub/` 与 `/links` 实现。Electron 原生 renderer 仍使用原来的 IPC。
+具体文件与环境差异见 [共享 Web 工作台](../../docs/todo/shared-web-workbench.md)。
+
+## code-shell-serve — 个人 Hub Web host
 
 在任意机器上把一个 workspace 变成浏览器可访问的 CodeShell：
 
 ```bash
-# 构建（repo 内）：core → coding → server → web app
-bun run build && bun run --cwd packages/web build:app
+# 构建（repo 内，先按部署指南安装依赖）
+bun run build:server
 
 # 启动
 node packages/server/dist/bin/code-shell-serve.js \
   --cwd ~/work/my-repo \
   --port 8790 \
-  --passcode <你的口令>     # 省略则首次启动生成随机口令并打印一次
+  --data-dir ~/codeshell-data
 ```
 
-浏览器打开 `http://127.0.0.1:8790`：输入口令（记住 cookie 后不再询问）→ 会话列表 / 新建对话 / 流式输出 / 工具审批 / 停止。
+首次启动会打印带 `#setup=` 的管理员初始化链接。创建管理员后，可在 Web「设置 → 模型与连接」添加连接并选择默认模型，也可以预先准备 Workspace 的 `.code-shell/settings.local.json`。没有可用模型时 HTTP 健康检查和配置界面仍可使用，对话需要先完成模型配置。
+
+当前 Web 工作台提供：
+
+- 对话、Markdown/代码/表格、模型提供的思考内容、工具结果、子任务、附件、审批与停止；刷新时恢复已保存历史和有界的当前运行事件。
+- 会话搜索、重命名、归档/恢复、Markdown/JSON 导出；Workspace 文件列表、文本/图片预览和认证下载。
+- 模型连接增删改、默认/辅助模型选择和真实连接测试；项目 Skills 增删改、启停、GitHub 预览安装/更新；MCP 配置、启停、工具权限和临时连接探测。
+- 独立 Link 页面：token 验证连接、重命名/断开、绑定宿主已登录 CLI，以及配置了应用 client ID 的 GitHub/GitLab 设备授权。
+- 单管理员登录、设备撤销、手机布局和 PWA 页面外壳。
+
+浏览器可以连接远端 Hub；Desktop 开启的 Web 可访问桌面已知项目，独立 Hub 固定一个 Workspace。Electron 原生窗口的远端执行目标、Hub 多 Workspace、团队账号隔离、插件市场和远程 Panel Host 仍属后续范围。
 
 ### 架构
 
 ```text
-浏览器 SPA（packages/web dist-app，说 core JSON-RPC 协议）
-   │  WS /ws（passcode/cookie 门禁）
+浏览器 SPA（packages/web dist-app）
+   │  HTTP /api/v1/* + WS /ws（管理员 Session Cookie 与 Origin 校验）
 headless serve（本包 serve/）
    │  stdio line-JSON-RPC（WorkerBridgeCore：按需 spawn、崩溃记账）
-agent-server-stdio worker（@cjhyy/code-shell-capability-coding）
+agent-server-stdio worker（Core 入口 + Coding 能力包）
 ```
 
-- 浏览器使用受限的 core 协议投影：serve 自己处理会话列表/详情，只允许向 worker 转发 `agent/run`、`agent/approve`、`agent/cancel`，并在转发前校验 workspace 与 session 归属。配置修改、任意 workspace 切换等原始 RPC 不对 Web 开放。
+- 浏览器使用受限的 Core 协议投影：serve 自己处理会话列表/详情，只允许向 worker 转发 `agent/run`、`agent/approve`、`agent/cancel`，并在转发前校验 Workspace 与 Session 归属。配置通过专用认证 HTTP 接口修改；任意配置 RPC 和 Workspace 切换不对 Web 开放。
 - 每个 tab 的请求 ID 会在 host 内重写，响应只回到发起 tab；`agent/streamEvent` 等通知才广播给所有已认证 tab，避免多 tab 使用相同本地 ID 时串包。
-- **访问控制只有 passcode + remember-cookie**（决策见 TODO 约束边界「服务端部署不做账号体系」）：scrypt 哈希存储、防爆破锁定、轮换口令使所有旧 cookie 失效。无注册登录、无多用户。
-- 默认只绑 `127.0.0.1`；`--host 0.0.0.0` 暴露到局域网是运维者的显式选择。公网建议走反向代理/tunnel 终结 TLS。
-- 会话、设置与凭据持久在 serve 独占的 worker data root（默认 `<data-dir>/worker`），不再读取宿主机默认 `~/.code-shell`；serve 或 worker 重启后浏览器重连即可恢复列表。
+- 默认使用 Hub 单管理员初始化、登录与可撤销 Session Cookie；`--auth passcode` 保留旧共享口令模式。当前只支持单用户、单 Workspace。
+- 默认只绑 `127.0.0.1`；远端可用 SSH 转发或 HTTPS 反向代理。HTTPS 部署需通过 `--public-url` 或对应环境变量配置实际公开 Origin，不能只改监听地址。
+- 会话持久在 serve 独占的 Worker data root（默认 `<data-dir>/worker`）；重启后可恢复列表与已保存历史，不会自动继续被中断的任务。活动运行缓冲有上限，超过后明确退回持久历史。
+- Server 与 Desktop 复用 Core 引擎、SettingsManager、Skills 管理及会话数据逻辑；共享的 `web` 库负责浏览器可用的消息投影。工具、MCP 和 Skill 脚本在服务端执行。桌面窗口、钥匙串、IPC 和 Panel Host 不随 Web 部署迁移。
+
+### Hub HTTP 接口分组
+
+这些是当前 Web 使用的受限接口，不是多租户 Gateway。除初始化、登录及健康检查等公开入口外，要求有效管理员登录；浏览器请求还受 Origin 校验。
+
+| 路径                         | 用途                                               |
+| ---------------------------- | -------------------------------------------------- |
+| `/api/v1/auth/*`             | 初始化、登录/退出、登录状态及 `/sessions` 设备管理 |
+| `/api/v1/uploads/:browserId` | 当前登录 Session 所属的受限附件暂存                |
+| `/api/v1/configuration/*`    | 模型连接、默认值和配置摘要                         |
+| `/api/v1/skills/*`           | 项目 Skill 管理与 GitHub 安装/更新                 |
+| `/api/v1/mcp/*`              | MCP 配置、继承、启停和连接探测                     |
+| `/api/v1/sessions/*`         | Workspace 内会话查询、标题、归档与导出             |
+| `/api/v1/files/*`            | Workspace 内文件列表、预览和下载                   |
+| `/api/v1/links/*`            | Link 连接、CLI 状态/绑定及设备授权                 |
+
+审批快照、设备 lease 和运行流通过 `/ws` 协议交换。配置写入 Workspace 本地层，任务运行期间拒绝修改（409），空闲保存后通过 Core 热更新用于下一次任务。列表和详情不返回已保存的模型密钥或 MCP 敏感值。模型测试会发送一次可能计费的请求；MCP 测试只连接及列工具，stdio 测试会启动配置的程序。完整的功能边界与限额见部署指南。
+
+Link 新连接写入宿主用户级 `CredentialStore`，不会放入模型配置的 `credentials[]`。
+Web 只绑定已经登录的 CLI，不接受任意命令或启动交互式登录。token 与设备授权在验证后保存，
+写入前重新检查发起者和连接版本；注销、设备撤销及关闭服务取消未完成操作。
+断开绕过运行忙碌门禁，以便 Core 凭证订阅取消活跃 LinkAction。
+当前 Link OAuth 过期需重新授权，没有自动续期或云端 Link Server；多设备共用一个宿主用户的连接。
 
 ### CLI 参数
 
-| 参数            | 默认                  | 说明                                         |
-| --------------- | --------------------- | -------------------------------------------- |
-| `--cwd`         | 当前目录              | worker 的 workspace 根                       |
-| `--port`        | 8790                  | 监听端口                                     |
-| `--host`        | 127.0.0.1             | 监听地址                                     |
-| `--passcode`    | （生成）              | 设置/轮换访问口令                            |
-| `--data-dir`    | `~/.code-shell/serve` | access.json 与隔离 worker data root 的父目录 |
-| `--static-root` | 自动解析 web dist-app | 覆盖静态资源目录                             |
+| 参数            | 默认                  | 说明                                                                                    |
+| --------------- | --------------------- | --------------------------------------------------------------------------------------- |
+| `--cwd`         | 当前目录              | worker 的 workspace 根                                                                  |
+| `--port`        | 8790                  | 监听端口                                                                                |
+| `--host`        | 127.0.0.1             | 监听地址                                                                                |
+| `--auth`        | hub                   | `hub` 管理员认证或 `passcode` 旧模式                                                    |
+| `--public-url`  | 根据监听地址生成      | 浏览器实际访问的根 Origin，也可用 `CODE_SHELL_SERVE_PUBLIC_URL`；非 loopback 要求 HTTPS |
+| `--passcode`    | 旧模式下自动生成      | 显式传入会默认选择 passcode 模式，不能与 `--auth hub` 同用                              |
+| `--data-dir`    | `~/.code-shell/serve` | 认证数据与隔离 Worker 数据根；设置 `CODE_SHELL_HOME` 时默认改为其下的 `serve`           |
+| `--static-root` | 自动解析 web dist-app | 覆盖静态资源目录                                                                        |
+| `--debug-logs`  | 关闭                  | 包含可能带任务正文的 Worker 诊断，仅写入私有日志                                        |
 
 ### Web 客户端开发
 
+先运行本地 Hub（后端默认 8790），再启动 Vite。开发时把 Hub 的公开 Origin 设为实际 Vite 地址，例如 `--public-url http://127.0.0.1:5173`；Vite 代理 `/api` 和 `/ws` 到 `127.0.0.1:8790`。浏览器始终使用该 Vite Origin 登录和访问：
+
 ```bash
-bun run --cwd packages/web dev:app   # vite dev server，/ws 代理到 127.0.0.1:8790
+bun run --cwd packages/web dev:app --host 127.0.0.1 --port 5173 --strictPort
 ```
+
+Docker 部署到其他机器见 [Docker 部署说明](../../docs/docker-deployment.md)。默认宿主机端口为 8791，可与原生 Node.js 服务并行。
+
+更新 Hub 后需重建并重启服务。Desktop Web 的入口构建到 `packages/desktop/out/mobile`，
+还依赖新的主进程 HTTP 接线，因此必须重新构建 Desktop 并重启应用；只更新 Hub 的 `dist-app`
+或刷新旧桌面的浏览器页面不会完成升级。

package/dist/bin/code-shell-project-runtime.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/code-shell-project-runtime.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runManagedProjectEntry } from "../project-runtime/managed-entry.js";
+runManagedProjectEntry().catch(() => {
+    // Secret-file parsing and credential validation can contain private values in
+    // their underlying errors. Expose only the operational failure to Docker logs.
+    console.error("[project-runtime] initialization failed; check this project's runtime configuration.");
+    process.exit(1);
+});

package/dist/desktop-web/http-api.d.ts

@@ -0,0 +1,43 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { TrustedDeviceStore } from "../mobile-remote/trusted-device-store.js";
+export interface DesktopWebRequestContext {
+    deviceId: string;
+    sessionId: string;
+    cwd: string;
+    /** Recheck both the paired device and Desktop's authoritative workspace registry. */
+    isAuthorized: () => Promise<boolean>;
+}
+export interface DesktopWebApiOptions {
+    devices: TrustedDeviceStore;
+    /** Desktop's existing title store directory: codeShellHome()/desktop. */
+    dataDir: string;
+    sessionRootDir: string;
+    /** Input is untrusted. Return only a workspace already known to Desktop. */
+    resolveWorkspace: (input: string | undefined, deviceId: string) => string | undefined | Promise<string | undefined>;
+    /**
+     * The existing Desktop AgentBridge owns this run/configuration admission lock.
+     * Reject active runs with status 409, hold the lock through write + hot reload,
+     * and notify the existing renderer/remote clients after a successful reload.
+     */
+    withConfigurationMutation: <T>(cwd: string, write: () => Promise<T>) => Promise<T>;
+    isRunning: (sessionId: string) => boolean;
+    onSessionsChanged?: (cwd: string, sessionId: string) => void;
+    /** Release owner-scoped resources contributed by handleExtra (for example Link probes). */
+    onSessionRevoked?: (sessionId: string) => void;
+    onClose?: () => void | Promise<void>;
+    /** Authenticated same-origin composition point, for example the shared Link API. */
+    handleExtra?: (request: IncomingMessage, response: ServerResponse, context: DesktopWebRequestContext) => boolean | Promise<boolean>;
+    now?: () => number;
+    sessionTtlMs?: number;
+}
+export interface DesktopWebHttpApi {
+    handle: (request: IncomingMessage, response: ServerResponse, context: {
+        baseUrl: string;
+    }) => Promise<boolean>;
+    /** Reopen after RemoteHostManager.stop(), without reviving previous cookies. */
+    start: () => void;
+    close: () => Promise<void>;
+    revokeDevice: (deviceId: string) => void;
+}
+/** HTTP facade over existing Desktop storage and worker callbacks; never starts a worker. */
+export declare function createDesktopWebApi(options: DesktopWebApiOptions): DesktopWebHttpApi;

package/dist/desktop-web/http-api.js

@@ -0,0 +1,376 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { createHubConfiguration, HubConfigurationError } from "../hub/configuration.js";
+import { createHubFiles } from "../hub/files.js";
+import { createHubMcpConfiguration } from "../hub/mcp-configuration.js";
+import { createHubSessions } from "../hub/session-management.js";
+import { createHubSkills } from "../hub/skills-management.js";
+const COOKIE = "cs_desktop_session";
+const SESSION_TTL = 30 * 60_000;
+const MAX_SESSIONS = 512;
+const MAX_WORKSPACES = 32;
+function json(response, status, body) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+    });
+    response.end(JSON.stringify(body));
+}
+function workspaceInput(request, url) {
+    const raw = request.headers["x-codeshell-workspace"];
+    let header;
+    try {
+        if (Array.isArray(raw))
+            throw new Error();
+        header = raw === undefined ? undefined : decodeURIComponent(raw);
+    }
+    catch {
+        throw new HubConfigurationError(400, "工作区请求头无效。");
+    }
+    const queries = url.searchParams.getAll("workspace");
+    if (queries.length > 1 || (header !== undefined && queries.length && header !== queries[0]))
+        throw new HubConfigurationError(400, "请求中的工作区不一致。");
+    // URLSearchParams has already decoded the query; literal percent signs in paths survive.
+    const input = header ?? queries[0];
+    if (input !== undefined && (!input || input.length > 4096 || input.includes("\0")))
+        throw new HubConfigurationError(400, "工作区路径无效。");
+    return input;
+}
+function sameOrigin(request, baseUrl) {
+    const expected = new URL(baseUrl);
+    if (!["http:", "https:"].includes(expected.protocol))
+        throw new HubConfigurationError(503, "桌面远程地址尚未就绪。");
+    // The manager supplies its bound/public URL. Never derive trust from Host or forwarded headers.
+    if (request.headers.host?.toLowerCase() !== expected.host.toLowerCase())
+        throw new HubConfigurationError(403, "请使用桌面显示的远程访问地址。");
+    const origin = request.headers.origin;
+    const readOnly = request.method === "GET" || request.method === "HEAD";
+    if ((origin !== undefined && origin !== expected.origin) ||
+        (!readOnly && origin === undefined) ||
+        request.headers["sec-fetch-site"] === "cross-site")
+        throw new HubConfigurationError(403, "请求必须来自同一个桌面远程页面。");
+    return expected;
+}
+function cookieToken(request) {
+    const tokens = (request.headers.cookie ?? "")
+        .split(";")
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith(`${COOKIE}=`))
+        .map((part) => part.slice(COOKIE.length + 1));
+    return tokens.length === 1 && /^[A-Za-z0-9_-]{43}$/.test(tokens[0]) ? tokens[0] : undefined;
+}
+async function credentials(request) {
+    if (request.headers["content-type"]?.split(";", 1)[0]?.trim() !== "application/json")
+        throw new HubConfigurationError(415, "请求必须使用 JSON 格式。");
+    const declared = Number(request.headers["content-length"] ?? 0);
+    if (!Number.isFinite(declared) || declared > 16 * 1024)
+        throw new HubConfigurationError(413, "设备认证内容过大。");
+    const chunks = [];
+    let bytes = 0;
+    const timeout = setTimeout(() => request.destroy(), 10_000);
+    timeout.unref();
+    try {
+        for await (const chunk of request) {
+            bytes += Buffer.byteLength(chunk);
+            if (bytes > 16 * 1024)
+                throw new HubConfigurationError(413, "设备认证内容过大。");
+            chunks.push(Buffer.from(chunk));
+        }
+        let input;
+        try {
+            input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        }
+        catch {
+            throw new HubConfigurationError(400, "设备认证格式无效。");
+        }
+        if (!input ||
+            Array.isArray(input) ||
+            Object.keys(input).some((key) => !["deviceId", "secretHash"].includes(key)) ||
+            typeof input.deviceId !== "string" ||
+            !input.deviceId ||
+            input.deviceId.length > 512 ||
+            typeof input.secretHash !== "string" ||
+            !input.secretHash ||
+            input.secretHash.length > 4096)
+            throw new HubConfigurationError(400, "设备认证格式无效。");
+        return { deviceId: input.deviceId, secretHash: input.secretHash };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** HTTP facade over existing Desktop storage and worker callbacks; never starts a worker. */
+export function createDesktopWebApi(options) {
+    const now = options.now ?? Date.now;
+    const ttl = options.sessionTtlMs ?? SESSION_TTL;
+    if (!Number.isSafeInteger(ttl) || ttl < 1000 || ttl > 24 * 60 * 60_000)
+        throw new Error("Desktop HTTP session lifetime must be between one second and one day");
+    const sessions = new Map();
+    const identities = new WeakMap();
+    const workspaces = new Map();
+    let generation = 0;
+    let closed = false;
+    function cancelSession(session) {
+        for (const services of workspaces.values()) {
+            services.configuration.cancelOwner(session.id);
+            services.mcp.cancelOwner(session.id);
+        }
+        // Optional extensions cannot prevent the primary transports from being revoked.
+        try {
+            options.onSessionRevoked?.(session.id);
+        }
+        catch {
+            // Their host-wide onClose callback remains a second cleanup opportunity.
+        }
+    }
+    function dropSession(token) {
+        const session = sessions.get(token);
+        if (session)
+            cancelSession(session);
+        sessions.delete(token);
+    }
+    function principal(token) {
+        if (closed || !token)
+            return;
+        const session = sessions.get(token);
+        if (!session)
+            return;
+        if (session.expiresAt <= now()) {
+            dropSession(token);
+            return;
+        }
+        // A signed-in cookie never bypasses a later revocation/removal from the on-disk device store.
+        const device = options.devices
+            .listDevices()
+            .find((row) => row.id === session.deviceId && !row.revokedAt);
+        if (!device) {
+            dropSession(token);
+            return;
+        }
+        return { session, device };
+    }
+    async function authorized(request) {
+        const identity = identities.get(request);
+        if (!identity || closed || identity.generation !== generation)
+            return false;
+        try {
+            if (principal(identity.token)?.session !== identity.session)
+                return false;
+            const resolved = await options.resolveWorkspace(identity.input, identity.session.deviceId);
+            // The resolver can yield while a device is revoked or the host is stopped.
+            return (resolved === identity.cwd &&
+                !closed &&
+                identity.generation === generation &&
+                principal(identity.token)?.session === identity.session);
+        }
+        catch {
+            return false;
+        }
+    }
+    async function owner(request) {
+        return (await authorized(request)) ? identities.get(request)?.session.id : undefined;
+    }
+    function createServices(cwd) {
+        const shared = {
+            cwd,
+            isAuthorized: authorized,
+            ownerId: owner,
+            withMutation: async (write) => {
+                try {
+                    return await options.withConfigurationMutation(cwd, write);
+                }
+                catch (error) {
+                    if (error instanceof HubConfigurationError)
+                        throw error;
+                    const status = error?.status;
+                    if (status === 409 || status === 503)
+                        throw new HubConfigurationError(status, status === 409
+                            ? "桌面正在运行任务，请等待任务结束后再保存。"
+                            : "桌面配置尚未重新载入，请稍后重试。");
+                    throw error;
+                }
+            },
+        };
+        const configuration = createHubConfiguration(shared);
+        const skills = createHubSkills({
+            ...shared,
+            dataDir: options.dataDir,
+            owner: async (req) => (await owner(req)) ?? null,
+        });
+        const mcp = createHubMcpConfiguration(shared);
+        const files = createHubFiles(shared);
+        const history = createHubSessions({
+            ...shared,
+            sessionRootDir: options.sessionRootDir,
+            dataDir: options.dataDir,
+            isRunning: options.isRunning,
+            onChanged: (id) => options.onSessionsChanged?.(cwd, id),
+        });
+        return {
+            configuration,
+            mcp,
+            active: 0,
+            async handle(request, response) {
+                for (const service of [configuration, skills, mcp, files, history])
+                    if (await service.handle(request, response))
+                        return true;
+                return false;
+            },
+            async close() {
+                configuration.close();
+                await Promise.allSettled([skills.close(), mcp.close(), files.close()]);
+            },
+        };
+    }
+    function servicesFor(cwd) {
+        let services = workspaces.get(cwd);
+        if (services)
+            workspaces.delete(cwd);
+        else {
+            if (workspaces.size >= MAX_WORKSPACES) {
+                const idle = [...workspaces].find(([, entry]) => entry.active === 0);
+                if (!idle)
+                    throw new HubConfigurationError(429, "同时打开的工作区过多，请稍后重试。");
+                workspaces.delete(idle[0]);
+                void idle[1].close();
+            }
+            services = createServices(cwd);
+        }
+        workspaces.set(cwd, services);
+        return services;
+    }
+    function status(session, device) {
+        return {
+            host: "desktop",
+            initialized: true,
+            authenticated: !!session,
+            ...(session && device
+                ? { session: { id: session.id, username: device.name, deviceName: device.name } }
+                : {}),
+        };
+    }
+    function setCookie(response, token, secure) {
+        response.setHeader("set-cookie", `${COOKIE}=${token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${token ? Math.floor(ttl / 1000) : 0}${secure ? "; Secure" : ""}`);
+    }
+    return {
+        start() {
+            closed = false;
+        },
+        revokeDevice(deviceId) {
+            for (const [token, session] of sessions)
+                if (session.deviceId === deviceId)
+                    dropSession(token);
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            generation++;
+            for (const session of sessions.values())
+                cancelSession(session);
+            sessions.clear();
+            const entries = [...workspaces.values()];
+            workspaces.clear();
+            await Promise.allSettled([...entries.map((entry) => entry.close()), options.onClose?.()]);
+        },
+        async handle(request, response, context) {
+            const url = new URL(request.url ?? "/", "http://localhost");
+            if (!url.pathname.startsWith("/api/v1/"))
+                return false;
+            try {
+                if (closed)
+                    throw new HubConfigurationError(503, "桌面远程服务已停止。");
+                const requestGeneration = generation;
+                const origin = sameOrigin(request, context.baseUrl);
+                const secure = origin.protocol === "https:";
+                const token = cookieToken(request);
+                if (request.method === "POST" && url.pathname === "/api/v1/desktop/session") {
+                    const input = await credentials(request);
+                    if (closed || requestGeneration !== generation)
+                        throw new HubConfigurationError(503, "桌面远程服务已停止。");
+                    const device = options.devices.authenticate(input.deviceId, input.secretHash);
+                    if (!device)
+                        throw new HubConfigurationError(401, "设备未配对或已被撤销，请在桌面重新配对。");
+                    const existing = principal(token);
+                    if (token && existing?.session.deviceId === device.id) {
+                        // Tabs share a cookie and WebSocket reconnects exchange it again.
+                        // Keep owner-scoped probes and Link authorizations alive across that handshake.
+                        existing.session.expiresAt = now() + ttl;
+                        setCookie(response, token, secure);
+                        json(response, 200, status(existing.session, device));
+                        return true;
+                    }
+                    // Re-exchange replaces only this browser's cookie. Other tabs/devices remain signed in.
+                    if (token)
+                        dropSession(token);
+                    for (const [key, session] of sessions)
+                        if (session.expiresAt <= now())
+                            dropSession(key);
+                    const own = [...sessions].filter(([, session]) => session.deviceId === device.id);
+                    while (own.length >= 8)
+                        dropSession(own.shift()[0]);
+                    while (sessions.size >= MAX_SESSIONS)
+                        dropSession(sessions.keys().next().value);
+                    const nextToken = randomBytes(32).toString("base64url");
+                    const session = { id: randomUUID(), deviceId: device.id, expiresAt: now() + ttl };
+                    sessions.set(nextToken, session);
+                    setCookie(response, nextToken, secure);
+                    json(response, 200, status(session, device));
+                    return true;
+                }
+                const current = principal(token);
+                if (request.method === "GET" &&
+                    ["/api/v1/auth/status", "/api/v1/auth"].includes(url.pathname)) {
+                    json(response, 200, status(current?.session, current?.device));
+                    return true;
+                }
+                if (request.method === "POST" && url.pathname === "/api/v1/auth/logout") {
+                    if (token)
+                        dropSession(token);
+                    setCookie(response, "", secure);
+                    json(response, 200, { ok: true });
+                    return true;
+                }
+                if (!current || !token)
+                    throw new HubConfigurationError(401, "设备连接已失效，请重新连接桌面。");
+                const input = workspaceInput(request, url);
+                const cwd = await options.resolveWorkspace(input, current.device.id);
+                if (closed ||
+                    generation !== requestGeneration ||
+                    principal(token)?.session !== current.session)
+                    throw new HubConfigurationError(401, "设备连接已失效，请重新连接桌面。");
+                if (!cwd || !isAbsolute(cwd))
+                    throw new HubConfigurationError(403, "只能访问桌面已知的项目或会话工作区。");
+                identities.set(request, { token, session: current.session, input, cwd, generation });
+                const services = servicesFor(cwd);
+                services.active++;
+                try {
+                    if (await services.handle(request, response))
+                        return true;
+                    if (await options.handleExtra?.(request, response, {
+                        deviceId: current.device.id,
+                        sessionId: current.session.id,
+                        cwd,
+                        isAuthorized: () => authorized(request),
+                    }))
+                        return true;
+                    json(response, 404, { error: "这个接口不适用于桌面远程模式。" });
+                }
+                finally {
+                    services.active--;
+                }
+            }
+            catch (error) {
+                json(response, error instanceof HubConfigurationError ? error.status : 500, {
+                    error: error instanceof HubConfigurationError
+                        ? error.message
+                        : "桌面远程请求失败，请稍后重试。",
+                });
+            }
+            return true;
+        },
+    };
+}

package/dist/hub/approval-lease.d.ts

@@ -0,0 +1,30 @@
+/** One runtime's live approvals. A lease reserves a decision; commit is one-shot. */
+export interface HubApproval {
+    requestId: string;
+    sessionId: string;
+    [key: string]: unknown;
+}
+export interface ApprovalLease {
+    requestId: string;
+    holderId: string | null;
+    expiresAt: number | null;
+}
+export declare class ApprovalLeases {
+    private readonly onChange;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly entries;
+    constructor(onChange: (lease: ApprovalLease) => void, ttlMs?: number, now?: () => number);
+    add(approval: HubApproval): void;
+    get(requestId: string): HubApproval | undefined;
+    snapshot(): HubApproval[];
+    claim(requestId: string, holderId: string): ApprovalLease;
+    /** Hold until worker acknowledgement; expiry must never permit duplicate decisions. */
+    submit(requestId: string, holderId: string): HubApproval;
+    release(requestId: string, holderId: string): void;
+    releaseHolder(holderId: string): void;
+    resolved(requestId: string): void;
+    retry(requestId: string): void;
+    clear(): void;
+    sweep(): void;
+}