dsh-remote-bridge 2.7.1 → 2.8.1

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 import { IncomingMessage, ServerResponse } from "node:http";
+import { WebSocket } from "ws";
 //#region src/shared/contracts.d.ts
 declare const DEVICE_SCOPES: readonly ["chat.read", "chat.write", "files.read", "files.write", "files.delete", "settings.read", "settings.write"];
 type DeviceScope = (typeof DEVICE_SCOPES)[number];
@@ -1411,6 +1412,22 @@ interface DshApiProxy {
     }): Promise<RpcResponse<{
       selected: ModelSelectionView;
     }>>;
+    /**
+     * 读会话投影基线（内核 `sessionController.projections`）。
+     *
+     * 供 agent-team / subagents 等只读投影的 WS 帧使用：投影里的 `agentTeam` /
+     * `subagentCatalog` 键给出团队成员、任务与子会话目录。会话不存在时内核返回 null。
+     */
+    projections(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+      };
+    }): Promise<RpcResponse<{
+      asOfSeq?: number;
+      kind?: string;
+      values: Record<string, unknown>;
+    } | null>>;
   };
   workspace: {
     list(request: {
@@ -1525,6 +1542,24 @@ interface DshApiProxy {
         answer: UserQuestionAnswer;
       };
     }): Promise<RpcResponse<UserQuestionAnswerOutcome>>;
+    /**
+     * 取消本桥接管的前台提问（question-cancel）。内核 userQuestions 服务无 cancel，
+     * 因此只能取消正阻塞 agent 的前台挂起项；带 timeout 的 continued 提问取消不了。
+     */
+    cancel(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        callId?: string;
+        rpcId?: string;
+      };
+    }): Promise<RpcResponse<{
+      accepted: true;
+      rpcId: string;
+    } | {
+      accepted: false;
+      reason: 'not-pending';
+    }>>;
   };
   events: {
     mux(request: {
@@ -1994,8 +2029,30 @@ declare class DshChatAdapter {
    * 映成 404/409，其余一律 400 —— 表达不了这几种区别。
    */
   answerUserQuestion(principal: Principal, sessionId: string, callId: string, answer: UserQuestionAnswer): Promise<void>;
+  /**
+   * 取消一条正挂在前台的用户提问（WS `question-cancel`）。
+   *
+   * 只能取消本桥接管、此刻正阻塞 agent 的前台提问；带 timeout 的 continued 提问
+   * 内核没有取消通道。取消成功后事件总线会推 userQuestions/dismissed（见桥的竞速收尾），
+   * 移动端据此关闭卡片。
+   */
+  cancelUserQuestion(principal: Principal, sessionId: string, ref: {
+    callId?: string;
+    rpcId?: string;
+  }): Promise<void>;
   models(principal: Principal, sessionId: string): Promise<SessionModelsView>;
   selectModel(principal: Principal, sessionId: string, selection: ModelSelectionView): Promise<ModelSelectionView>;
+  /**
+   * 读会话投影基线（agent-team / subagents 帧用）。
+   *
+   * 会话不存在（内核返回 null）映射成 404 SESSION_NOT_FOUND；取不到投影不打 500，
+   * 由调用方按 PROTOCOL 回 projectionState:'unavailable'。这里只做鉴权 + 透传。
+   */
+  sessionProjections(principal: Principal, sessionId: string): Promise<{
+    asOfSeq?: number;
+    kind?: string;
+    values: Record<string, unknown>;
+  }>;
   listCommands(principal: Principal, sessionId: string): Promise<CommandDescriptorView[]>;
   executeCommand(principal: Principal, sessionId: string, line: string): Promise<CommandExecutionView>;
   isSessionAuthorized(principal: Principal, sessionId: string): Promise<boolean>;
@@ -2110,6 +2167,32 @@ declare class AuthService {
   requireRoot(principal: Principal, rootId: string): void;
 }
 //#endregion
+//#region src/host/capabilities.d.ts
+/**
+ * 运行时**不可用**的能力位：服务端此刻做不了这些事，就不该声明。
+ *
+ * ## 为什么必须过滤（这是本节最重要的一条）
+ *
+ * 能力位的全部意义是让客户端把「服务端不支持」与「本来就没有」分开
+ * （见文件头的说明）。而 `jobController` 是**可选宿主服务**：0.2.0-rc.2 上没有它，
+ * 三个 `/jobs` 端点在那套内核上根本不会被挂载（`index.ts` 直接不下发，路由返回 404）。
+ * 若 `connection.ready` 仍然宣告 `job-list-v1`，客户端按位探测后就会去打一个必然
+ * 404 的端点 —— 这恰好是这份清单本身想消灭的那种「静默少一个功能」。
+ *
+ * ## 为什么按「能力位 → 依赖的服务」映射，而不是在调用点手写过滤
+ *
+ * 声明与端点必须**同源**。把「哪个位依赖哪个可选服务」写在一处，将来再加一个
+ * 可选服务只需要在这里补一行；散在调用点就会漂。
+ */
+/** 运行时能力开关。缺省（不传键）一律当作可用，见 {@link availableCapabilities}。 */
+interface CapabilityFlags {
+  jobs?: boolean;
+  /** 宿主 cordis 服务 `ctx.schedule` 在不在（`dsh-schedule` 插件未装时为 false）。 */
+  schedule?: boolean;
+  /** 内核 typert Gateway 在不在（`speech` 目录与转写都要经它）。 */
+  speech?: boolean;
+}
+//#endregion
 //#region src/host/event-bus.d.ts
 declare class WorkspaceEventBus {
   private readonly listeners;
@@ -2117,6 +2200,197 @@ declare class WorkspaceEventBus {
   subscribe(listener: (event: WorkspaceEvent) => void): () => void;
 }
 //#endregion
+//#region src/host/ws-host-services.d.ts
+/** 供 WS 域处理器调用的远程服务句柄。 */
+interface HostRemoteHandle {
+  invoke(namespace: string, method: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+  stream(namespace: string, method: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<AsyncIterable<unknown>>;
+}
+//#endregion
+//#region src/host/ws-handler.d.ts
+/**
+ * `/ws/mobile` 的可调参数。
+ *
+ * 三个都有默认值，且**必须可注入**：默认值（32 / 30 s / 512）在单测里既等不起
+ * （30 s 的心跳周期）也压不满（512 深度要发五百多帧）。可注入才能把「第 33 条 429」
+ * 「两个周期踢人」「溢出补 resync」这三条**文档承诺的行为**变成可断言的用例。
+ */
+interface MobileGatewayOptions {
+  /** 同时允许的连接数上限，默认 {@link DEFAULT_MOBILE_MAX_CONNECTIONS}。 */
+  maxConnections?: number;
+  /** 心跳周期（毫秒），默认 {@link DEFAULT_MOBILE_HEARTBEAT_INTERVAL_MS}。 */
+  heartbeatIntervalMs?: number;
+  /** 单连接发送队列深度，默认 {@link DEFAULT_MOBILE_QUEUE_LIMIT}。 */
+  queueLimit?: number;
+}
+declare class MobileGatewayWsHandler {
+  private readonly database;
+  private readonly chat;
+  private readonly auth;
+  private readonly capabilitiesFlags;
+  private readonly sockets;
+  /**
+   * 当前异步上下文里正在处理的那一帧客户端请求的 `requestId`。
+   *
+   * **为什么必须是 AsyncLocalStorage 而不是实例字段/闭包变量**：`webSocket.on('message')`
+   * 里是 `void this.handleMessage(...)`（不 await），同一条连接可以同时有多个请求在途；
+   * 任何「先存起来、发送时再读」的共享槽位都会把并发请求的 id 串到一起。ALS 把上下文
+   * 绑定在**这条 await 链**上，`await` 穿过它、并发分支各持一份，互不可见。
+   */
+  private readonly frameRequestId;
+  private settingsService;
+  private filesService;
+  /**
+   * 可选内核远程服务（typertGateway + owner peer）。存在时才启用定时任务与官方语音代理；
+   * 缺失（老内核）时对应帧回结构化 unavailable，引导 REST 兜底。
+   */
+  private hostRemote;
+  /** 语音管理器：跨连接共享（全局转写并发计数需要进程级单一实例）。 */
+  private speech;
+  /** 文件分块下载/上传管理器：跨连接共享（每连接并发计数 + spool 落盘需要进程级状态）。 */
+  private fileTransfer;
+  /**
+   * 装配全局模型目录与文件浏览依赖。这两个域需要 DshSettingsAdapter / FileService，
+   * 它们在 index.ts 里晚于 RemoteApiServer 构造（router 装配期），故用 setter 注入，
+   * 而不是塞进构造函数（避免 server↔router 的构造顺序环）。
+   */
+  attachHostServices(services: {
+    settings: MobileGatewayWsHandler['settingsService'];
+    files: MobileGatewayWsHandler['filesService'];
+  }): void;
+  /**
+   * 装配内核可选远程服务（定时任务 / 官方语音）。在 index.ts apply 期取到
+   * typertGateway+connection 后注入；传入 undefined 表示当前内核不提供（优雅降级）。
+   */
+  attachRemoteServices(remote: HostRemoteHandle | undefined): void;
+  /** 同时允许的连接数上限（鉴权后计数；server.ts 在 Upgrade 前据此回 429）。 */
+  private readonly maxConnections;
+  /** 心跳周期：每周期 ping 一次，连续两个周期没回 pong 就 terminate。 */
+  private readonly heartbeatIntervalMs;
+  /** 单连接发送队列深度（溢出时先丢可重建帧）。 */
+  private readonly queueLimit;
+  /** 心跳定时器（首个连接接入时惰性启动，{@link stop} 时清掉）。 */
+  private heartbeatTimer;
+  constructor(database: WorkspaceDatabase, chat: DshChatAdapter, auth: AuthService, events: WorkspaceEventBus, capabilitiesFlags: CapabilityFlags, options?: MobileGatewayOptions);
+  private readonly eventBridge;
+  /**
+   * 判定这次 upgrade 是否属于 /ws/mobile。server.ts 负责实际的 WebSocket 升级，
+   * 升级完成后再把 WebSocket 交给 onConnection。
+   */
+  ownsPath(req: IncomingMessage): boolean;
+  /**
+   * 对已经升级好的 WebSocket 做子协议鉴权、状态登记、帧分发。
+   * 返回 false 表示不属于此处理器（由调用方决定后续，通常是 socket.destroy()）。
+   */
+  onConnection(webSocket: WebSocket, req: IncomingMessage): boolean;
+  private handlePairingConnection;
+  private handleTokenConnection;
+  private acceptSocket;
+  /**
+   * 连接建立后补推待处理的审批/提问。逐连接按本连接身份做会话授权过滤（复用
+   * chat.replayPending* 内部的 isSessionAuthorized），绝不因别的设备授权过就串推。
+   * 失败静默：与 server.ts 同名方法一致，重放失败不应让连接崩掉（实时事件仍走桥）。
+   *
+   * @param onlySessionId - 给 subscribe 帧用：只补推该会话的待处理项；缺省补全部。
+   */
+  private replayPendingInteractions;
+  private sendHello;
+  private stateOf;
+  private principalToDeviceView;
+  /**
+   * 收到一条文本帧的入口：解码 → 校验 → **绑定 requestId 上下文** → 分发。
+   *
+   * 这里同时是唯一的异常兜底点。调用方是 `webSocket.on('message')` 里的
+   * `void this.handleMessage(...)`（不 await），任何从这里冒出去的 rejection 都会成为
+   * 进程级 unhandledRejection —— DSH 宿主装了 `installFailLoud`，直接 `proc.exit(1)`。
+   * 而 `handleHistory` 等基础帧是直接 `await this.chat.*`，一次越权的 `sessionId` 就能抛
+   * `ApiError(404, 'SESSION_NOT_FOUND')`。所以分发必须整体包在 try/catch 里。
+   */
+  private handleMessage;
+  /** 把一帧已解码、已校验的请求分发给对应的处理器（异常由 {@link handleMessage} 兜底）。 */
+  private routeFrame;
+  private handlePing;
+  private handleSubscribe;
+  private handleUnsubscribe;
+  /**
+   * 处理 `message` 帧：若未带 sessionId，先在用户首个授权根目录下建一个空会话；
+   * 再把内容送进 chat.prompt。响应 `sent`，客户端后续通过 WS 的 `event` 帧
+   * （或 REST /api/v1/events）拿回流式增量。
+   */
+  private handleMessageFrame;
+  private handleWorkspaces;
+  private handleSessions;
+  private handleHistory;
+  private handleAttachment;
+  /**
+   * 向一条连接发一条帧（带背压队列）。
+   *
+   * 应答帧统一在这里回显 `requestId`：从 {@link frameRequestId} 取**当前异步上下文**的
+   * requestId，交给 {@link withRequestIdEcho} 决定要不要塞进 `data`。处理器无需再各自
+   * 复制一遍（已手写回显的处理器不受影响 —— 注入规则是「`data` 里已有就不覆盖」）。
+   */
+  private sendFrame;
+  /**
+   * 压入发送队列，队列满时**先牺牲可重建的帧**。
+   *
+   * 与 `/api/v1/events`（server.ts 的 `enqueue`）同一套取舍，只是这里没有「可重建事件
+   * 标记表」可用，改用 kind 判据。为什么不能无脑 `shift()` 丢最旧：最旧的那条可能正是
+   * 某次请求的**应答**，丢掉它客户端就会一直等到超时（而它等的那个东西其实早成功了），
+   * 反过来一条 `chat.message.delta` 丢了只影响一句的流式观感，history 一拉就齐。
+   *
+   * 被丢的帧数累加到 `state.dropped`，由 {@link drain} 在排空后补一条
+   * `connection-resync-required` 告知客户端 —— **静默丢帧比丢帧本身更糟**。
+   */
+  private enqueue;
+  private sendError;
+  /**
+   * 把分发过程中冒出来的异常变成一条 `error` 帧（范式与各域处理器的 `reportError` 一致）。
+   *
+   * **这里的 try/catch 不是多余的**：`sendFrame` 第一行就是 `this.stateOf(webSocket)`，而
+   * `teardown` 会在 `close`/`error` 时把连接从 `sockets` 摘掉。连接已断时 `stateOf` 抛
+   * `ApiError(4001, 'NOT_AUTHENTICATED')` —— 在 catch 块里再抛一次，就等于没修。
+   */
+  private reportFrameError;
+  /**
+   * 把队列里的帧逐条发出去，排空后按需补一条「你漏了 N 帧」的告知帧。
+   *
+   * 补发放在**排空之后**而不是溢出当场：溢出那一刻队列正满，插一条进去还得再挤掉别人；
+   * 等排空再补，既不会二次溢出，也能把同一段时间内多次溢出合并成一条（`dropped` 累加）。
+   */
+  private drain;
+  /** 拒绝未鉴权连接（401 close code）。 */
+  private closeUnauthorized;
+  /** 用自定义 close code 关闭，并附简短理由。 */
+  private closeWithCode;
+  /** 关闭所有连接（server.stop 时调用）。 */
+  stop(timeoutMs?: number): Promise<void>;
+  /**
+   * 心跳循环：每 `heartbeatIntervalMs` ping 一次，**连续错过两个周期**才 terminate。
+   *
+   * 为什么必须有这一步：`/ws/mobile` 是手机上的长连接，切网、熄屏、NAT 表项过期都会留下
+   * **半开连接** —— 内核这边没有任何事件，TCP 要等自己超时才报错（默认以分钟计），期间
+   * 这条连接一直占着 `sockets` 里的额度、每次广播还白查一遍库。API 文档承诺「连续错过
+   * 2 个心跳周期 terminate」，这里就是把它兑现。
+   *
+   * 两个刻意的取舍：
+   * - `terminate()` 而不是 `close()`：对端已经不在，优雅挥手没人收，只会多等一个超时；
+   *   `close`/`error` 里注册的 `teardown` 会照常摘表、摘事件桥、中止语音与文件传输；
+   * - 存活标记用底层 `pong` 控制帧：客户端库自动回，不需要业务代码配合（业务层的
+   *   `ping` 帧是另一回事，用于测 RTT）。
+   */
+  private startHeartbeat;
+  private clearHeartbeat;
+  /**
+   * 连接数上限（供 server.ts 在 **Upgrade 之前**判定是否回 429）。
+   *
+   * 为什么要在 upgrade 前判：升级之后就只能发 WS 关闭码，`Retry-After` 根本无法表达，
+   * 客户端也拿不到「稍后再试」这个语义（只会看到一次莫名其妙的断连）。
+   */
+  connectionLimit(): number;
+  /** 当前连接数（供 metrics / 观测）。 */
+  connectionCount(): number;
+}
+//#endregion
 //#region src/host/host-service-probe.d.ts
 interface ServiceProbe {
   name: string;
@@ -2480,6 +2754,12 @@ declare class FileService {
   private notify;
 }
 //#endregion
+//#region src/host/bff-rest.d.ts
+/** 宿主 `ctx.schedule` 服务在本层只需要 `create`（远程面没有新建，见 `bff-schedule.ts` 文件头）。 */
+interface ScheduleCreatePort {
+  create: (sessionId: string, request: Record<string, unknown>) => Promise<unknown>;
+}
+//#endregion
 //#region src/host/router.d.ts
 interface RemoteOperationView {
   id: string;
@@ -2541,10 +2821,33 @@ interface RouterOptions {
    * 可选：不注入则这些端点返回 404，测试不必每条都补一个字段。
    */
   jobs?: JobAdapter;
+  /**
+   * 内核 typert Gateway 句柄：REST 的语音与定时任务读面（`bff-*.ts`）。
+   *
+   * 可选，且**缺席不是错误**：老内核上它本来就不存在，此时语音回
+   * `200 {available:false}`、定时任务读面回 503 —— 与 `/ws/mobile` 帧的
+   * `speech/unavailable`、`schedule/unavailable` 是**同一个**判据。
+   */
+  hostRemote?: HostRemoteHandle;
+  /**
+   * 宿主 `ctx.schedule` 服务：只有它有 `create`（远程面没注册，见
+   * `bff-schedule.ts` 文件头）。可选，缺席时 `POST /chat/schedules` 回 503。
+   */
+  schedule?: ScheduleCreatePort;
 }
 declare class ApiRouter {
   private readonly options;
+  /**
+   * REST 对等面（分块上传 / 定时任务 / 语音）的分发体。
+   *
+   * 构造在这里而不是 `index.ts`：它只依赖 `RouterOptions` 已有的东西
+   * （`database.dataDir`、`chat`、`hostRemote`、`schedule`），多一个外部装配点
+   * 只会多一条会漂的接线。
+   */
+  private readonly bff;
   constructor(options: RouterOptions);
+  /** 停机清理（分块 spool）。由 `index.ts` 的生命周期钩子调用。 */
+  dispose(): Promise<void>;
   handle(req: IncomingMessage, res: ServerResponse, stripPrefix?: string): Promise<void>;
   private dispatch;
   private dispatchManagement;
@@ -2650,9 +2953,7 @@ interface RemoteApiServerOptions {
    * 为什么在构造参数里而不是全局变量：能力位是**这台服务端此刻**能做什么，
    * 同一进程里可能有多个实例（测试、重绑），用实例参数才不会被互相污染。
    */
-  capabilities?: {
-    jobs?: boolean;
-  };
+  capabilities?: CapabilityFlags;
 }
 declare class RemoteApiServer implements RemoteControl {
   private readonly options;
@@ -2665,6 +2966,8 @@ declare class RemoteApiServer implements RemoteControl {
   private readonly operations;
   private readonly sockets;
   private readonly webSockets;
+  /** 移动端网关 WebSocket（/ws/mobile）：与 /api/v1/events 并存，WS 优先、REST 兜底。 */
+  private readonly wsMobile;
   private readonly eventsAbort;
   private unsubscribeEvents;
   /** 所有连接的 drain 完成信号；`Promise.all` 它们即可等排空。 */
@@ -2677,6 +2980,16 @@ declare class RemoteApiServer implements RemoteControl {
   private readonly highWaterMarkBytes;
   private readonly heartbeatIntervalMs;
   constructor(options: RemoteApiServerOptions);
+  /**
+   * 注入全局模型目录与文件浏览依赖（index.ts 在 router 装配期调用）。
+   * 这两个域依赖晚于本类构造的 DshSettingsAdapter / FileService，故走 setter 而非构造参数。
+   */
+  attachMobileHostServices(services: Parameters<MobileGatewayWsHandler['attachHostServices']>[0]): void;
+  /**
+   * 注入内核可选远程服务（typertGateway + owner peer），用于定时任务与官方语音 WS 代理。
+   * 传入 undefined（老内核无这两个服务）时相关帧回结构化 unavailable，引导 REST 兜底。
+   */
+  attachMobileRemoteServices(remote: Parameters<MobileGatewayWsHandler['attachRemoteServices']>[0]): void;
   start(): Promise<void>;
   stop(): Promise<void>;
   status(operationId?: string): {