dsh-remote-bridge 2.7.1 → 2.8.0

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,100 @@ 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
+declare class MobileGatewayWsHandler {
+  private readonly database;
+  private readonly chat;
+  private readonly auth;
+  private readonly capabilitiesFlags;
+  private readonly sockets;
+  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;
+  constructor(database: WorkspaceDatabase, chat: DshChatAdapter, auth: AuthService, events: WorkspaceEventBus, capabilitiesFlags: CapabilityFlags);
+  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;
+  private handleMessage;
+  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;
+  /** 向一条连接发一条帧（带背压队列）。 */
+  private sendFrame;
+  private sendError;
+  /** 把队列里的帧逐条发出去。 */
+  private drain;
+  /** 拒绝未鉴权连接（401 close code）。 */
+  private closeUnauthorized;
+  /** 用自定义 close code 关闭，并附简短理由。 */
+  private closeWithCode;
+  /** 关闭所有连接（server.stop 时调用）。 */
+  stop(timeoutMs?: number): Promise<void>;
+  /** 当前连接数（供 metrics / 观测）。 */
+  connectionCount(): number;
+}
+//#endregion
 //#region src/host/host-service-probe.d.ts
 interface ServiceProbe {
   name: string;
@@ -2480,6 +2657,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 +2724,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 +2856,7 @@ interface RemoteApiServerOptions {
    * 为什么在构造参数里而不是全局变量：能力位是**这台服务端此刻**能做什么，
    * 同一进程里可能有多个实例（测试、重绑），用实例参数才不会被互相污染。
    */
-  capabilities?: {
-    jobs?: boolean;
-  };
+  capabilities?: CapabilityFlags;
 }
 declare class RemoteApiServer implements RemoteControl {
   private readonly options;
@@ -2665,6 +2869,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 +2883,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): {