dsh-remote-bridge 2.6.0 → 2.7.0

package/lib/index.d.ts

@@ -26,6 +26,24 @@ interface DeviceView {
   createdAt: number;
   lastSeenAt?: number;
   revokedAt?: number;
+  /**
+   * 设备自称/被推断出的平台与型号（`android` / `harmonyos` / …）。
+   *
+   * **可选**：老设备从未上报过就是 `undefined`，客户端必须能接受缺省。
+   * 这两个字段只用于界面显示与排查，**不参与任何授权判断** —— 它们是客户端
+   * 自称的，不是可信身份。
+   */
+  platform?: string;
+  model?: string;
+  /**
+   * `name` 是怎么来的，决定后续能不能自动改名。
+   *
+   * - `default`：配对时的占位名（`'Android 设备'` 之类）。设备第一次带身份
+   *   连上来时**允许**被自动改成「平台 · 型号」。
+   * - `detected`：由探测到的身份自动生成。后续身份变了仍可再自动更新。
+   * - `declared`：用户手工改的。**永不再自动覆盖** —— 用户起的名比机器猜的准。
+   */
+  nameSource?: 'default' | 'detected' | 'declared';
 }
 interface FileEntryView {
   name: string;
@@ -179,6 +197,7 @@ declare class WorkspaceDatabase {
    */
   exchangePairing(code: string, deviceName: string, options?: {
     requestId?: string;
+    nameSource?: 'default' | 'declared';
   }): {
     token: string;
     device: DeviceView;
@@ -186,6 +205,47 @@ declare class WorkspaceDatabase {
   authenticate(token: string): AuthenticatedDevice | undefined;
   getActiveDevice(id: string): AuthenticatedDevice | undefined;
   private hydrateDevice;
+  /**
+   * 记录一次探测到的设备身份，必要时顺手把占位名改成「平台 · 型号」。
+   *
+   * 时序说明：配对时桥只知道「有个设备要连」，真正的平台与型号要等设备
+   * **第一次发请求**才拿得到。所以这个方法由认证路径调用（见 `auth.ts`
+   * 的 `principal`），而不是配对路径。
+   *
+   * ## 什么时候改名
+   *
+   * 只有 `name_source` 是 `default`（配对时的占位名）或 `detected`（上次自动
+   * 生成的）才改名。`declared`（用户手工改的）**永不动** —— 用户起的名比机器
+   * 猜的准，而且他能改一次就能改第二次，但机器每次连接都覆盖就再也留不住了。
+   *
+   * 老库的 `name_source` 是 NULL：那些行里的名字多半是硬编码的「Android 设备」，
+   * 但**也可能是用户手工改过的**（此前没有任何改名通道，所以实际上只有占位名；
+   * 不过万一有人直接改过库，我们不能替他决定）。保守起见把 NULL 当作
+   * `declared` 处理 —— 名字不动，只补 platform/model 两列。
+   *
+   * ## 为什么不做成「每次请求都写库」
+   *
+   * 调用方只在**探测结果与库里不同**时才调这里（见 `auth.ts`），所以正常情况
+   * 下一台设备一生只写一次。这不是性能考虑，而是避免把一次读请求变成写请求：
+   * 写请求会碰 WAL、会影响 `devicesRevisionCounter`，进而触发全体客户端重拉设备表。
+   *
+   * @returns 是否真的改了库（调用方据此决定要不要递增设备版本号）。
+   */
+  recordDeviceIdentity(id: string, identity: {
+    platform?: string;
+    model?: string;
+    suggestedName?: string;
+  }): boolean;
+  /**
+   * 用户手工改名。
+   *
+   * 一旦走这条路，`name_source` 就变成 `declared`，此后任何自动探测都**不再**
+   * 覆盖它。这是「用户意图优先于机器推断」的唯一实现点，所以单独一个方法而不是
+   * 塞进 `updateDevice`：权限变更与改名是两件不同的事，审计动作也不该混。
+   */
+  renameDevice(id: string, name: string, options?: {
+    requestId?: string;
+  }): DeviceView;
   listDevices(): DeviceView[];
   isDeviceActive(id: string): boolean;
   /**
@@ -333,6 +393,9 @@ declare class WorkspaceDatabase {
   private dropRootsUniqueConstraint;
   /** `roots` 表是否已有指定列。 */
   private hasRootColumn;
+  /** `devices` 表是否已有指定列。 */
+  private hasDeviceColumn;
+  private hasColumn;
 }
 //#endregion
 //#region src/host/settings-namespace.d.ts
@@ -553,9 +616,13 @@ declare class DshSettingsAdapter {
   /**
    * @param options.writeNamespaces 额外允许手机端写入的设置命名空间（精确 ns 或
    *   `前缀*`），与内置策略（`ui-*` / 以 `locale` 结尾）叠加；默认为空。
+   * @param options.allowPrivateProviderHosts 允许供应商 `baseURL` 指向的私网 / 回环
+   *   host 白名单（默认空 = 一律拒绝）。要连本地 LLM 的部署方显式填，理由见
+   *   `provider-url-policy.ts` 文件头。
    */
   constructor(api: SettingsApiProxy, options?: {
     writeNamespaces?: readonly string[];
+    allowPrivateProviderHosts?: readonly string[];
   });
   /**
    * 列出全部设置命名空间（通用设置面的读侧）。
@@ -572,6 +639,8 @@ declare class DshSettingsAdapter {
    */
   mutateNamespace(ns: string, ops: unknown, expectedRevision?: number): Promise<SettingsNamespaceEntry>;
   private get writeNamespaces();
+  /** 交给地址策略的选项；集中一处，三个入口不会各配各的。 */
+  private get baseURLOptions();
   /** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
   private settingsService;
   listProviders(): Promise<{
@@ -587,14 +656,38 @@ declare class DshSettingsAdapter {
       message: string;
     }[];
   }>;
-  updateProvider(providerId: string, patch: ProviderPatch): Promise<void>;
-  createProvider(input: CustomProviderCreate): Promise<void>;
+  /**
+   * 更新供应商配置。
+   *
+   * 返回 `baseURLHost`（仅当本次 patch 动了 `baseURL` 时存在）供路由层写审计：
+   * 攻击者可以用 discover 把凭据发到任意地址，事后必须能从审计里看出「打了哪」。
+   * 只记 host 不记完整 URL —— path/query 可能带凭据，审计表不该成为新的泄露点。
+   */
+  updateProvider(providerId: string, patch: ProviderPatch): Promise<{
+    baseURLHost?: string;
+  }>;
+  createProvider(input: CustomProviderCreate): Promise<{
+    baseURLHost: string;
+  }>;
   removeProvider(providerId: string, expectedRevision?: number): Promise<void>;
+  /**
+   * 发现供应商可用模型。
+   *
+   * `draft.baseURL` 是**临时覆盖**（不写配置），但内核会带着该供应商已配置的真实
+   * 凭据去请求它 —— 这正是 SEC-H11 的窃取路径：攻击者把自己的服务器填进来即可收到
+   * `Authorization: Bearer <真实 key>`。因此临时覆盖与持久化写入过同一道地址策略。
+   *
+   * 返回 `baseURLHost` 供路由层审计；不传 `baseURL` 时（用配置里的地址）同样返回，
+   * 这样「打了哪个地址」在任何情况下都能追溯。
+   */
   discover(providerId: string, draft: {
     baseURL?: string;
     api?: string;
     apiKey?: string;
-  }): Promise<ProviderModelView[]>;
+  }): Promise<{
+    models: ProviderModelView[];
+    baseURLHost?: string;
+  }>;
   /**
    * 取一个 provider 的上下文（目录条目 + 设置命名空间 + 当前 profile）。
    *
@@ -622,6 +715,13 @@ declare class DshSettingsAdapter {
    */
   private invalidateProviderContext;
   private loadProviderContext;
+  /**
+   * 该供应商当前是否已经存了凭据。
+   *
+   * 单独一次 `credentials.describe` 只在「要换 baseURL host」时才调 —— 那是罕见路径，
+   * 而正常保存（改 models / 显示名 / 协议）不该为此多付一次内核往返。
+   */
+  private providerHoldsCredential;
 }
 //#endregion
 //#region src/host/dsh-0.2-bridge.d.ts
@@ -996,9 +1096,29 @@ interface LlmLike {
    * `this.ctx.llm.resolveModelInfo(...)` 再查 `inputModalities`）。入口要与内核
    * 得出同一个结论，只能查同一份元数据 —— 名字、前缀、家族表都是启发式，会漂。
    */
-  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
-    inputModalities?: readonly string[];
-  } | undefined>;
+  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfoLike | undefined>;
+}
+/**
+ * `ctx.llm.resolveModelInfo()` 返回值里桥消费的那几个字段。
+ *
+ * 内核的 `LlmResolvedModelInfo` 比这更宽（还有 `reasoning` / `systemPromptUpdate`
+ * / `toolUpdate`），这里只声明真正读的：上下文容量与默认输出上限。
+ *
+ * **为什么必须从 `resolveModelInfo` 拿、而不是从 `modelCatalog()` 拿**：
+ * 0.2.x 的 `ModelCatalogModel` 只有 `{ id, name, description?, reasoning? }` ——
+ * 目录里**没有** `contextWindow` / `maxTokens` / `inputModalities`。这三个只在
+ * `LlmResolvedModelInfo`（= `LlmModelInfo` + `context` + `defaultMaxTokens`）里。
+ * 目录条目自带这两个字段是 1.x 的旧形状，2.x 拆开了。
+ */
+interface LlmResolvedModelInfoLike {
+  /** 输入模态；`undefined` = 未知，显式缺 `image` = 负能力。 */
+  readonly inputModalities?: readonly string[];
+  /** 上下文容量（请求 + 响应合计 token 上限）；内核不知道时不存在。 */
+  readonly context?: {
+    readonly contextWindow: number;
+  };
+  /** 调用方不显式给上限时，adapter 会用的每请求输出上限。 */
+  readonly defaultMaxTokens?: number;
 }
 /** Host services the bridge consumes; assembled by `src/index.ts` from `ctx`. */
 interface Dsh02HostServices {
@@ -1551,6 +1671,19 @@ interface ChatSessionView {
   origin?: 'subagent';
   pendingInteraction?: 'approval';
 }
+/**
+ * 建会话的可选参数。
+ *
+ * `reuseBlank` 是**桥**加的语义，不是内核字段：DSH 0.2.1 起桌面端点「新会话」会回到
+ * 那个工作区已有的空白会话，而内核 RPC 不做这层挑选（见 `reusableBlankId`）。
+ * 桥默认照桌面语义走（省略即 `true`），但留一个 `false` 让调用方要「无论如何新建一个」
+ * 时能要得到 —— 老客户端从来不带这个字段，行为因此是**新增**而不是**变更**。
+ */
+interface CreateSessionOptions {
+  sessionId?: string;
+  agentPreset?: string;
+  reuseBlank?: boolean;
+}
 interface PendingApprovalView {
   id: string;
   sessionId: string;
@@ -1706,20 +1839,49 @@ declare class DshChatAdapter {
     defaultPreset: string;
   }>;
   selectAgentPreset(principal: Principal, sessionId: string, agentPreset: string): Promise<string>;
-  createSessionInWorkspace(principal: Principal, workspaceId: string, options: {
-    sessionId?: string;
-    agentPreset?: string;
-  }): Promise<{
+  createSessionInWorkspace(principal: Principal, workspaceId: string, options: CreateSessionOptions): Promise<{
     id: string;
     agentPreset?: string;
   }>;
-  createSession(principal: Principal, rootId: string, relativePath: string, options: {
-    sessionId?: string;
-    agentPreset?: string;
-  }): Promise<{
+  createSession(principal: Principal, rootId: string, relativePath: string, options: CreateSessionOptions): Promise<{
     id: string;
     agentPreset?: string;
   }>;
+  /**
+   * 挑一个可复用的空白会话 —— DSH 0.2.1 起桌面端的「New Session 回到空白会话」语义。
+   *
+   * **内核自己不做这件事。** `sessionController.create` 只有调用方显式传了 `sessionId`
+   * 才会走 `claim` / `reuseLive` 去复用；不传就无条件 `createMinted` 新建一个。
+   * 「跳过 preset 不匹配的空白会话」那层挑选写在**客户端**（`dsh-client-ui-workspace`
+   * 的 `connectWorkspace` → `createInWorkspace`）里，而桥走 REST 直连内核，没有这一层 ——
+   * 于是手机端每点一次「新会话」就多一个空白会话，攒成一串永远没人用的空壳。
+   *
+   * 这里把客户端那条判据原样搬过来（`blank && cwd 匹配 && 未归档 && preset 匹配`），
+   * 取用顺序也照抄：**按内核返回的列表顺序取第一个**，不自己按时间排序 —— 同一份数据
+   * 在桌面与手机上应当落到同一条会话上，桥没有理由发明第三种顺序。
+   *
+   * preset 的口径也与内核一致：空白会话**没声明** preset 时对任何预设都算可用
+   * （只有 `typeof listed === 'string'` 才比较）。「没声明」不等于「声明了别的」——
+   * 把前者当成不匹配会让所有老会话都挑不中。
+   */
+  private reusableBlankId;
+  /**
+   * 工作区维度上找一个可复用的空白会话。
+   *
+   * 归属判据用**内核自己的两个字段**：`session.cwd === workspace.path` 且
+   * `workspace.sessionIds` 含它 —— 与客户端 `createInWorkspace` 逐字同义。
+   * 这里重新拉一次原始 workspace 列表（而不是复用 `listWorkspaces` 的投影结果），
+   * 因为 `ChatWorkspaceView` 刻意不含 `sessionIds` 与绝对路径。
+   */
+  private blankSessionInWorkspace;
+  /**
+   * 绝对路径维度上找一个可复用的空白会话（老客户端的 `rootId` + `path` 入口）。
+   *
+   * 这里没有 workspace 摘要可用，判据就只剩「同一 cwd」—— 与客户端按 workspace
+   * 挑选相比少了两道（`sessionIds` 归属、workspace 存在性），但那两道在
+   * `rootId` + `path` 这条路上本来就由授权根解析替代了。
+   */
+  private blankSessionAtPath;
   history(principal: Principal, sessionId: string, options: {
     beforeSeq?: number;
     maxMessages?: number;
@@ -1927,6 +2089,14 @@ declare class AuthService {
   principal(req: IncomingMessage, options?: {
     allowAdmin?: boolean;
   }): Principal;
+  /**
+   * 把本次请求探测到的身份记进库，并（在允许时）更新设备显示名。
+   *
+   * 吞掉一切异常的理由见调用点注释：设备名是显示信息，不该成为连接的前置条件。
+   *
+   * @returns 改名成功时的新名字；没改名（或探测不到）时 `undefined`。
+   */
+  private recordIdentity;
   /**
    * `/manage/**` 的守门人。
    *
@@ -2696,6 +2866,18 @@ interface Config {
    * 遥控器交出去（理由见 docs/project/SECURITY.md）。
    */
   settingsWriteNamespaces?: readonly string[];
+  /**
+   * 允许供应商 `baseURL` 指向的私网 / 回环 host 白名单（默认空 = 一律拒绝）。
+   *
+   * 默认拒绝的理由：手机端改 `baseURL` 就等于把模型请求（含 `Authorization:
+   * Bearer <真实 key>`）引到任意地址，这是 SEC-H11 的窃取路径。默认拒绝把
+   * 「谁能连内网」变成部署方的显式决定。
+   *
+   * 要连本地 LLM（ollama / LM Studio 之类）时填这里，推荐带端口：
+   * `["127.0.0.1:11434", "localhost:1234"]`。带端口的条目只放行该端口，裸
+   * host 条目放行该主机的任意端口（面更大）。规则见 `src/host/provider-url-policy.ts`。
+   */
+  allowPrivateProviderHosts?: readonly string[];
 }
 interface HostContext extends Dsh02HostServices {
   webServer: Parameters<typeof attachEmbeddedRoutes>[0];