dsh-remote-bridge 2.2.3 → 2.3.0

package/lib/index.d.ts

@@ -6,6 +6,17 @@ interface RootView {
   id: string;
   label: string;
   createdAt: number;
+  /**
+   * 这是不是插件自动登记的「DSH 工作区」根。
+   *
+   * 用户要求：默认把当前 DSH 的工作目录作为一个授权根显示出来，**不可删除**，
+   * 但可以正常访问（手机端照常浏览）。标记只影响**删除**这一件事 ——
+   * 它在数据库里就是一条普通的根，`files.*` 授权、配对、写盘全走同一套。
+   *
+   * 不写成 `readonly`，是为了让 REST 契约保持「服务端给什么就是什么」：
+   * 老客户端不认识这个字段会忽略它，行为不变。
+   */
+  builtin?: boolean;
 }
 interface DeviceView {
   id: string;
@@ -69,11 +80,49 @@ declare class WorkspaceDatabase {
   private readonly db;
   constructor(dataDir: string);
   close(): void;
+  /**
+   * 导出 `roots` 的建表语句（只读，诊断与迁移测试用）。
+   *
+   * 存在的理由：迁移要判断「UNIQUE 还在不在」，单看 `PRAGMA table_info` 看不出来 ——
+   * 表结构读出来一模一样，区别在约束上。这个方法让「重建真的发生了」可以被断言，
+   * 而不是靠迁移没报错来推测。
+   */
+  dumpSchema(): string;
   getSetting(key: string): string | undefined;
   setSetting(key: string, value: string): void;
-  addRoot(inputPath: string, label?: string): Promise<StoredRoot>;
+  addRoot(inputPath: string, label?: string, options?: {
+    allowDuplicate?: boolean;
+  }): Promise<StoredRoot>;
   listRoots(): StoredRoot[];
   getRoot(id: string): StoredRoot | undefined;
+  /**
+   * 登记「DSH 工作区」根 —— **幂等**。
+   *
+   * 用户要求：当前 DSH 的工作目录要显示成一个授权根，**不可删除、但可以正常访问**。
+   * 它不是另起一张表，而是**一条普通的根**加一个 `builtin` 标记：配对、`files.*`
+   * 授权、回收站、写盘全走现成逻辑，少一套需要同步维护的规则。
+   *
+   * ## 同目录已有一条普通根时，另起一条而不是复用它
+   *
+   * 这是实测踩到的现实情况：用户早于这个功能**自己**加过同一条目录（本机那条是
+   * 10-08 手工加的），路径和 DSH 工作区一模一样。
+   *
+   * 初版在这里「尊重用户选择」直接返回，结果就是**内置项永远登记不上** —— 因为它
+   * 每次都撞上那条已有的普通根然后什么都不做。界面上那个「不可删除」也就永远出不来。
+   * 用户的选择和功能的正确性在这里是冲突的：用户要的是「这条要不可删」，不是
+   * 「这条不能变」。
+   *
+   * 所以改成**另起一条**：用户原来那条保持可删（那是他的目录，他有权删），内置那条
+   * 独立存在。代价是列表里同一个路径出现两行 —— 这是「两条记录、两种权限」的必然
+   * 结果，比让功能失效或擅自改他的配置都更可接受。
+   *
+   * 幂等不再靠 UNIQUE（它已经被去掉了），而是靠「已存在 `builtin = 1` 的同路径就
+   * 直接返回」。插件**每次启动都可以无脑调一次**。
+   *
+   * 只有传入路径确实存在才登记：工作区可能被用户删掉，这时留一条指向虚空的授权根，
+   * 手机浏览时会一路报错，比不显示更糟。
+   */
+  ensureBuiltinRoot(realPath: string, label: string): Promise<StoredRoot | undefined>;
   removeRoot(id: string): void;
   createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number): {
     code: string;
@@ -89,7 +138,39 @@ declare class WorkspaceDatabase {
   listDevices(): DeviceView[];
   isDeviceActive(id: string): boolean;
   updateDevice(id: string, scopes: DeviceScope[], rootIds: string[]): DeviceView;
+  /**
+   * 撤销设备 = **直接删除这一行**（用户要求：已撤销的不显示，并自动从数据库中删除）。
+   *
+   * 原先是打 `revoked_at` 标记保留行，两处都不好：
+   * - 界面上会出现一长串灰掉的「已撤销」，本机实测堆到了 32 条，全是历史测试与旧设备；
+   * - 行留着就等于凭据的哈希还在库里，是个长期负担 —— 令牌已经没用了，留着没有意义。
+   *
+   * 删除是安全的，因为：
+   * - `device_roots` 是 `ON DELETE CASCADE`，授权行自动清掉；
+   * - `audit.actor_id` 是**普通字符串不是外键**，审计留痕（谁在什么时候撤了谁）一条不少；
+   * - `authenticate` 仍保留 `revoked_at IS NULL` 作为兜底，万一有别处留下的标记行，
+   *   它们依然登不进来 —— 两层保险不冲突。
+   */
   revokeDevice(id: string): void;
+  /**
+   * 一次性清理历史遗留的「标记式」撤销设备（`revoked_at IS NOT NULL` 的行）。
+   *
+   * 撤销改成直接删除之前，每次撤销都只是打个标记，于是库越用越臃肿 —— 本机实测堆到
+   * **32 条**，全是历史测试探针和早已弃用的旧手机，界面上就是一长串灰字。
+   *
+   * 幂等：没有这种行时返回 0，不报错。插件每次启动调一次即可。
+   * 走 `revokeDevice` 的删除语义，但**不能**借它写 `device.revoke` 审计 ——
+   * 那会把「系统清理」记成管理员逐个撤销，审计会失真。清理本身只写一条汇总。
+   */
+  /**
+   * 仅供测试：造一行「撤销改成删除之前」的标记式撤销数据。
+   *
+   * 真实场景来自历史库（每次撤销只打 `revoked_at` 标记，于是越积越多）。测试需要个
+   * 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
+   * 并起一个自见其明的名字，免得有人把它当成正常 API。
+   */
+  markRevokedForTest(id: string): void;
+  purgeRevokedDevices(): number;
   insertTrash(record: TrashRecord): void;
   updateTrashStatus(id: string, status: string): void;
   getTrash(id: string): TrashRecord | undefined;
@@ -103,1109 +184,1151 @@ declare class WorkspaceDatabase {
   } | undefined;
   saveIdempotent(deviceId: string, key: string, status: number, body: unknown): void;
   private migrate;
+  /** `roots.real_path` 上是否还带 UNIQUE 约束。 */
+  private rootsPathIsUnique;
+  /**
+   * 重建 `roots` 去掉 UNIQUE。
+   *
+   * 这是一次**有真实数据风险**的操作，所以每一步都写清楚理由：
+   * - `PRAGMA foreign_keys=OFF`：`device_roots.root_id` 引用 `roots(id)`，而重建要
+   *   DROP 掉被引用的那张表。开着外键会直接失败。
+   * - 事务：`new_roots` 建好、数据搬完、**最后**才 DROP 老表并改名。中途失败会整体
+   *   回滚，原表原封不动。
+   * - 搬数据用显式列名而不是 `SELECT *`：老表可能还没有 `builtin` 列（两种迁移顺序
+   *   都可能出现），按列名搬才不会在某一台机器上错位。
+   */
+  private dropRootsUniqueConstraint;
+  /** `roots` 表是否已有指定列。 */
+  private hasRootColumn;
 }
 //#endregion
-//#region src/host/chat-adapter.d.ts
-interface RpcResponse<T> {
-  result: {
-    ok: true;
-    value: T;
-  } | {
-    ok: false;
-    error: {
-      code: string;
-      message: string;
-      details?: unknown;
-    };
-  };
+//#region src/host/settings-adapter.d.ts
+interface SettingsNamespaceView {
+  ns: string;
+  schema?: unknown;
+  value: unknown;
+  base?: unknown;
+  user?: unknown;
+  revision: number;
 }
-/**
- * 一条 prompt 的内容片段 —— 与 DSH 0.2.x 的 `PromptContentPart` 一一对应。
- *
- * 三种形态的代价差别很大，值得写清楚：
- * - `text`  直接发送；
- * - `image` 字节**内联**在 payload 里（base64），一次调用完成，但请求体膨胀约 33%，
- *   所以客户端必须先限制原图大小，别等 413；
- * - `file`  的 `receiptId` 必须来自**先前的**上传调用，并在同一次 prompt 里绑定，
- *   否则凭证会被回收。
- */
-type PromptContentPart = {
-  type: 'text';
-  text: string;
-} | {
-  type: 'image';
-  mediaType: string;
-  data: string;
-  name?: string;
-} | {
-  type: 'file';
-  receiptId: string;
-};
-interface DshApiProxy {
-  respond(message: {
-    type: 'client-response';
-    rpcId: string;
-    result: {
-      ok: true;
-      value: unknown;
-    };
-  }): Promise<{
-    accepted: true;
-  } | {
-    accepted: false;
-    reason: 'not-pending' | 'bad-response';
-  }>;
-  sessions: {
-    list(request: {
-      rpcId: string;
-      payload: {
-        cursor?: string;
-      };
-    }): Promise<RpcResponse<{
-      items: DshSessionSummary[];
-    }>>;
-    create(request: {
-      rpcId: string;
-      payload: {
-        cwd?: string;
-        workspaceId?: string;
-        sessionId?: string;
-        agentPreset?: string;
-      };
-    }): Promise<RpcResponse<{
-      sessionId: string;
-      agentPreset?: string;
-    }>>;
-    history(request: {
+interface ConfigurableProvider {
+  provider: string;
+  displayName: string;
+  settingsNs: string;
+  settingsPath: string[];
+  active: boolean;
+  declared?: boolean;
+}
+interface SettingsApiProxy extends DshApiProxy {
+  settings: {
+    describe(request: {
       rpcId: string;
-      payload: {
-        sessionId: string;
-        beforeSeq?: number;
-        maxMessages?: number;
-      };
+      payload: Record<string, never>;
     }): Promise<RpcResponse<{
-      events: unknown[];
-      hasMore: boolean;
-      projections?: unknown;
+      writable: boolean;
+      hasDocument: boolean;
+      namespaces: SettingsNamespaceView[];
     }>>;
-    prompt(request: {
+    mutate(request: {
       rpcId: string;
       payload: {
-        sessionId: string;
-        mode: 'queue' | 'steer';
-        content: PromptContentPart[];
-        clientTimeZone?: string;
+        ns: string;
+        ops: Array<{
+          op: 'set';
+          path: string[];
+          value: unknown;
+        } | {
+          op: 'unset';
+          path: string[];
+        }>;
+        expectedRevision?: number;
       };
-    }): Promise<RpcResponse<{
-      accepted: true;
-      command?: unknown;
-    }>>;
-    /**
-     * 上传一个文件，换取 prompt 可引用的凭证（`receiptId`）。
-     * `data` 是文件字节的**标准 base64**。
-     */
-    uploadAttachment(request: {
+    }): Promise<RpcResponse<SettingsNamespaceView>>;
+  };
+  credentials: {
+    describe(request: {
       rpcId: string;
       payload: {
-        sessionId: string;
-        data: string;
-        name?: string;
+        refs: string[];
       };
     }): Promise<RpcResponse<{
-      receiptId: string;
-      name: string | null;
+      credentials: Record<string, {
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+      }>;
     }>>;
-    /**
-     * 按 id 取回附件字节。
-     *
-     * `attachmentId` 形如 `sha256:<hex>`（**含冒号**，客户端必须 URL 编码）。
-     * 返回 `Uint8Array` 而不是 base64：图片动辄上百 KB，多一次编解码纯属浪费。
-     *
-     * **必须带 `sessionId`**：内核要靠它读会话事件、取出这张图的真实 ref，
-     * 再据此做完整性校验（详见 chat-adapter 的 readAttachment 注释）。
-     */
-    readAttachment(request: {
+    set(request: {
       rpcId: string;
       payload: {
-        sessionId: string;
-        attachmentId: string;
+        ref: string;
+        value: string;
       };
-    }): Promise<RpcResponse<{
-      bytes: Uint8Array;
-      mediaType: string;
-    }>>;
-    /**
-     * 取回一张**交接图片**的字节（纯文本模型发图时，图片被落成工作区文件）。
-     *
-     * 与 [readAttachment] 的区别：那一个取内核附件存储里的图（走
-     * `sessionController.attachment`），这一个取插件自己写进 `.dsh-images/`
-     * 的交接件。手机端用它把图片**显示**给人看；消息里的路径文本照旧留给模型。
-     */
-    readHandoffImage(request: {
+    }): Promise<RpcResponse<Record<string, never>>>;
+    unset(request: {
       rpcId: string;
       payload: {
-        sessionId: string;
-        name: string;
+        ref: string;
       };
-    }): Promise<RpcResponse<{
-      bytes: Uint8Array;
-      mediaType: string;
-    }>>;
-    cancel(request: {
+    }): Promise<RpcResponse<Record<string, never>>>;
+  };
+  llm: {
+    providers(request: {
       rpcId: string;
-      payload: {
-        sessionId: string;
-      };
+      payload: Record<string, never>;
     }): Promise<RpcResponse<{
-      accepted: true;
+      providers: ConfigurableProvider[];
     }>>;
-    rename(request: {
+    models(request: {
       rpcId: string;
-      payload: {
-        sessionId: string;
-        title: string;
-      };
+      payload: Record<string, never>;
     }): Promise<RpcResponse<{
-      title: string;
-      seq: number;
+      groups: ModelProviderGroupView[];
+      failures: {
+        provider: string;
+        message: string;
+      }[];
     }>>;
-    fork(request: {
+    discoverModels(request: {
       rpcId: string;
       payload: {
-        sessionId: string;
-        atSeq?: number;
+        settingsNs: string;
+        provider?: string;
+        baseURL?: string;
+        api?: string;
+        apiKey?: string;
       };
     }): Promise<RpcResponse<{
-      sessionId: string;
+      models: ProviderModelView[];
     }>>;
-    models(request: {
-      rpcId: string;
-      payload: {
-        sessionId: string;
-      };
-    }): Promise<RpcResponse<SessionModelsView>>;
-    selectModel(request: {
-      rpcId: string;
-      payload: {
-        sessionId: string;
-        provider: string;
-        model: string;
-        reasoningEffort?: string;
-      };
-    }): Promise<RpcResponse<{
-      selected: ModelSelectionView;
-    }>>;
-  };
-  workspace: {
-    list(request: {
-      rpcId: string;
-      payload: Record<string, never>;
-    }): Promise<RpcResponse<{
-      items: DshWorkspaceSummary[];
-      archivedSessionIds: string[];
-    }>>;
-    create(request: {
-      rpcId: string;
-      payload: {
-        path: string;
-      };
-    }): Promise<RpcResponse<{
-      workspace: DshWorkspaceSummary;
-      created: boolean;
-    }>>;
-    rename(request: {
-      rpcId: string;
-      payload: {
-        workspaceId: string;
-        title: string;
-      };
-    }): Promise<RpcResponse<{
-      workspace: DshWorkspaceSummary;
-    }>>;
-    delete(request: {
-      rpcId: string;
-      payload: {
-        workspaceId: string;
-      };
-    }): Promise<RpcResponse<{
-      deleted: true;
-    }>>;
-    archiveSession(request: {
-      rpcId: string;
-      payload: {
-        sessionId: string;
-      };
-    }): Promise<RpcResponse<{
-      archivedSessionIds: string[];
-    }>>;
-  };
-  agentPresets: {
-    list(request: {
-      rpcId: string;
-      payload: Record<string, never>;
-    }): Promise<RpcResponse<{
-      presets: DshAgentPresetSummary[];
-      authorable: boolean;
-      hasDocument: boolean;
-    }>>;
-    select(request: {
-      rpcId: string;
-      payload: {
-        sessionId: string;
-        agentPreset: string;
-      };
-    }): Promise<RpcResponse<{
-      agentPreset: string;
-    }>>;
-  };
-  /**
-   * 用户问题（内核 `ctx.userQuestions`，即 ask_user_question 工具）。
-   *
-   * 为什么单开一个命名空间而不是塞进 `sessions`：它由**另一个内核服务**提供
-   * （`@deepseek-ai/dsh-user-questions`），在一条没装它的 profile 上是**可选能力** ——
-   * 分开之后，「这个能力不在」和「这个会话有问题」在类型上就分得开。
-   */
-  userQuestions: {
-    /**
-     * 列出还能回答的问题（内核 `continued(agent)`）。
-     * 没有 live agent、或没有该服务时返回空列表 —— 冷会话是常态，不该报错。
-     */
-    list(request: {
-      rpcId: string;
-      payload: {
-        sessionId: string;
-      };
-    }): Promise<RpcResponse<{
-      items: UserQuestionView[];
-    }>>;
-    /** 提交答案；失败原因见 [UserQuestionAnswerOutcome]。 */
-    answer(request: {
-      rpcId: string;
-      payload: {
-        sessionId: string;
-        callId: string;
-        answer: UserQuestionAnswer;
-      };
-    }): Promise<RpcResponse<UserQuestionAnswerOutcome>>;
-  };
-  events: {
-    mux(request: {
-      rpcId: string;
-      payload: Record<string, never>;
-    }, signal: AbortSignal): AsyncIterable<{
-      rpcId: string;
-      payload: Record<string, unknown>;
-    }>;
-    host(request: {
-      rpcId: string;
-      payload: Record<string, never>;
-    }, signal: AbortSignal): AsyncIterable<{
-      rpcId: string;
-      payload: Record<string, unknown>;
-    }>;
   };
 }
-interface ModelSelectionView {
-  provider: string;
-  model: string;
-  reasoningEffort?: string;
-}
-interface ModelReasoningView {
-  efforts: {
-    id: string;
-    name: string;
-    description?: string;
-  }[];
-  defaultEffort?: string;
-}
-interface ModelProviderGroupView {
+interface ProviderModelView {
   id: string;
-  name: string;
-  models: {
-    id: string;
-    name: string;
-    description?: string;
-    contextWindow?: number;
-    maxTokens?: number;
-    reasoning?: ModelReasoningView;
-  }[];
-}
-interface SessionModelsView {
-  current: ModelSelectionView;
-  routable: boolean;
-  groups: ModelProviderGroupView[];
-  failures: {
-    provider: string;
-    message: string;
-  }[];
-}
-interface CommandDescriptorView {
-  name: string;
-  description: string;
-  input?: {
-    hint: string;
-  };
-}
-interface CommandExecutionView {
-  commandId: string;
-  result: {
-    kind: 'success' | 'error';
-    text?: string;
-    sourceEventSeq?: number;
-  };
-}
-interface DshCommandRuntime {
-  list(agent: unknown): readonly CommandDescriptorView[];
-  execute(agent: unknown, line: string, signal: AbortSignal): Promise<CommandExecutionView | undefined>;
-}
-interface DshAgentRegistry {
-  get(sessionId: string): unknown | undefined;
+  name?: string;
+  contextWindow?: number;
+  maxTokens?: number;
 }
-interface DshCommandServices {
-  commands: DshCommandRuntime;
-  agents: DshAgentRegistry;
+interface ProviderConfigView {
+  baseURL?: string;
+  api?: string;
+  displayName?: string;
+  thinking?: string;
+  reasoningEffort?: string;
+  models: ProviderModelView[];
+  modelsInherited?: boolean;
 }
-interface DshSessionSummary {
-  sessionId: string;
-  updatedAt: number;
-  running: boolean;
-  blank: boolean;
-  cwd?: string;
-  agentPreset?: string;
-  parentSessionId?: string;
-  origin?: 'subagent';
-  projections?: {
-    asOfSeq: number;
-    values: Record<string, unknown>;
+interface ProviderView {
+  id: string;
+  displayName: string;
+  active: boolean;
+  declared?: boolean;
+  configurable: boolean;
+  configured: boolean;
+  removable: boolean;
+  credential: {
+    ref: string;
+    configured: boolean;
+    source?: string;
+    writable: boolean;
   };
+  config: ProviderConfigView;
 }
-interface DshWorkspaceSummary {
-  workspaceId: string;
-  path: string;
-  title: string;
-  sessionIds: string[];
-  createdAt: string;
-  updatedAt: string;
+interface ProviderPatch {
+  displayName?: string | null;
+  baseURL?: string | null;
+  api?: string | null;
+  apiKey?: string | null;
+  thinking?: string | null;
+  reasoningEffort?: string | null;
+  models?: ProviderModelView[];
+  expectedRevision?: number;
 }
-interface DshAgentPresetSummary {
+interface CustomProviderCreate {
   id: string;
-  trust: 'system' | 'user';
-  isDefault: boolean;
-  name?: string;
-  description?: string;
-  broken?: string;
+  displayName?: string;
+  baseURL: string;
+  api: string;
+  apiKey?: string;
+  models: ProviderModelView[];
+  expectedRevision?: number;
 }
-interface ChatSessionView {
-  id: string;
-  rootId: string;
-  cwd: string;
-  updatedAt: number;
-  running: boolean;
-  blank: boolean;
-  title?: string;
-  workspaceId?: string;
-  workspaceTitle?: string;
-  agentPreset?: string;
-  parentSessionId?: string;
-  origin?: 'subagent';
-  pendingInteraction?: 'approval';
+interface CustomProviderCapability {
+  available: boolean;
+  protocols: string[];
+  revision?: number;
 }
-interface PendingApprovalView {
-  id: string;
-  sessionId: string;
-  toolName: string;
-  reason?: string;
-  detail?: string;
-  risk: 'standard' | 'full-access';
-  requestedAt: number;
+declare class DshSettingsAdapter {
+  private readonly api;
+  constructor(api: SettingsApiProxy);
+  listProviders(): Promise<{
+    writable: boolean;
+    revisionByNamespace: Record<string, number>;
+    customProvider: CustomProviderCapability;
+    providers: ProviderView[];
+  }>;
+  catalog(): Promise<{
+    groups: ModelProviderGroupView[];
+    failures: {
+      provider: string;
+      message: string;
+    }[];
+  }>;
+  updateProvider(providerId: string, patch: ProviderPatch): Promise<void>;
+  createProvider(input: CustomProviderCreate): Promise<void>;
+  removeProvider(providerId: string, expectedRevision?: number): Promise<void>;
+  discover(providerId: string, draft: {
+    baseURL?: string;
+    api?: string;
+    apiKey?: string;
+  }): Promise<ProviderModelView[]>;
+  private providerContext;
 }
+//#endregion
+//#region src/host/dsh-0.2-bridge.d.ts
 /**
- * 一条「还能回答」的用户问题 —— 内核 `userQuestions.continued()` 的一行。
+ * Prompt content a 0.2.x Host accepts — mirrors its `PromptContentPart` union.
  *
- * 为什么类型是宽松的、而不是照抄内核的 `AskUserQuestionItem`：内核往 item 或
- * question 上加过字段（`intent` 就是一例），手机端该自己决定要不要用，
- * 不该等插件跟着发版。所以这里只钉住三个**契约字段**，其余原样透传。
+ * 权威定义在 `chat-adapter.ts`（协议层），这里只是复用它，避免两处各写一遍
+ * 然后悄悄漂移。
  */
-interface UserQuestionView {
-  callId: string;
-  /** 内核 `UserQuestionState`：'open' 或 'continued'；本端点只返回 continued。 */
-  state: string;
-  /** 问题项**原样**透传（id / question / detail? / header? / options? / multiSelect? / intent?）。 */
-  questions: unknown[];
-  /** 内核以后加的字段照样透传，不在这里裁剪。 */
-  [key: string]: unknown;
-}
-/** 一条问题的答案（内核 `AskUserQuestionAnswerItem`）。 */
-interface UserQuestionAnswerItem {
-  /** 被回答的问题 id，必须与请求里的问题 id 对上。 */
-  id: string;
-  /** 选中的选项 label；多选时可能多项。 */
-  selected: string[];
-  /** 可选的「其他」自由文本。 */
-  custom?: string;
-}
-/** 一次提交的完整答案批次（内核 `AskUserQuestionAnswer`）：一次调用里的每个问题各占一项。 */
-interface UserQuestionAnswer {
-  answers: UserQuestionAnswerItem[];
-}
+type PromptContentPartLike = PromptContentPart;
 /**
- * 「把答案送进内核」的结果。
+ * `ctx.fileUploads`：内核的文件上传服务。
  *
- * 刻意**不走 RpcResponse 的 error 通道**：`unwrapDsh` 只认 `not-found` /
- * `busy` / `locked` 三种 code 去映射 HTTP 状态，其余一律 400 —— 而这里需要区分
- * 409 / 400 / 503。做成**值**之后由 adapter 决定 HTTP 状态，
- * 和 approvals 的 `respond()` 返回 `{ accepted: false, reason }` 是同一个套路。
+ * 由内核的 `@deepseek-ai/dsh-client-file-upload` 以 cordis 服务的形式暴露，
+ * 因此插件**不需要**把字节转发到内核的 HTTP 路由（那条路由只绑 loopback，手机也到不了）。
  */
-type UserQuestionAnswerFailure =
-/** 内核里没有这个 callId 的悬空问题（`answer()` 返回了 false）。 */
-'not-pending' |
-/** 已经有一条回复在排队（内核 `REPLY_QUEUED`）。重复提交不是服务器故障。 */
-'reply-queued' |
-/** 答案批次没有「一问一答」地对齐（内核 `BAD_ANSWER`）。 */
-'answer-invalid' |
-/** 这个 agent 现在不接受人工回答（非 live root / 被别的 agent 拥有），或会话没有 live agent。 */
-'not-answerable' |
-/** 这套 DSH 构建里压根没有 `ctx.userQuestions` 服务。 */
-'unavailable';
-type UserQuestionAnswerOutcome = {
-  accepted: true;
-} | {
-  accepted: false;
-  reason: UserQuestionAnswerFailure;
-};
-interface ChatWorkspaceView {
-  id: string;
-  title: string;
-  rootId: string;
-  path: string;
-  createdAt: string;
-  updatedAt: string;
+interface FileUploadsLike {
+  upload(agent: unknown, request: {
+    data: string;
+    name?: string;
+  }, signal: AbortSignal): Promise<{
+    receiptId: string;
+  }>;
+  /**
+   * 把凭证绑定到某次 prompt。返回值不 commit 的话凭证会被回收 ——
+   * 所以调用方必须在 prompt **成功之后** commit()。
+   */
+  bindPrompt(agent: unknown, receiptIds: readonly string[], requestId: string): {
+    commit(): void;
+  };
 }
-interface AgentPresetView {
-  id: string;
-  name: string;
-  description?: string;
-  trust: 'system' | 'user';
-  isDefault: boolean;
-  available: boolean;
+/**
+ * `ctx.attachments`：内核的附件存储。
+ *
+ * 为什么会话里的图片必须经由它：消息**发送时**图片是 base64 内联的，但**存进历史后**
+ * 会变成 `{type:'image', attachment:{attachmentId:'sha256:…'}}` 这样的引用 ——
+ * 字节在附件存储里，不在事件里。客户端只拿到 id，所以必须有一步「按 id 取字节」，
+ * 否则历史里的图片一律显示不出来。
+ */
+interface AttachmentStoreLike {
+  readImage(
+  /**
+   * 附件引用。
+   *
+   * `attachmentId` 是唯一的**定位**字段（内核用 `ID_PATTERN.exec()` 取出 sha256
+   * 再拼 `objects/<前两位>/<sha>`）；而 `mediaType` / `bytes` / `width` / `height`
+   * 参与读后**完整性校验** —— 缺任何一项都会抛 `ATTACHMENT_CORRUPT`，
+   * 哪怕字节已经正确读出来了。
+   */
+  ref: {
+    attachmentId: string;
+    mediaType?: string;
+    bytes?: number;
+    width?: number;
+    height?: number;
+  }, signal?: AbortSignal): Promise<{
+    ref: {
+      mediaType: string;
+    };
+    data: Uint8Array;
+  }>;
 }
-declare class DshChatAdapter {
-  private readonly api;
-  private readonly database;
-  private readonly commandServices?;
-  private readonly sessionRootIds;
-  private readonly sessionRootLookups;
-  private readonly pendingApprovals;
-  constructor(api: DshApiProxy, database: WorkspaceDatabase, commandServices?: DshCommandServices | undefined);
-  listSessions(principal: Principal): Promise<ChatSessionView[]>;
-  listWorkspaces(principal: Principal): Promise<ChatWorkspaceView[]>;
-  createWorkspace(principal: Principal, rootId: string, relativePath: string): Promise<ChatWorkspaceView>;
-  renameWorkspace(principal: Principal, workspaceId: string, title: string): Promise<ChatWorkspaceView>;
-  deleteWorkspace(principal: Principal, workspaceId: string): Promise<void>;
-  listAgentPresets(): Promise<AgentPresetView[]>;
-  selectAgentPreset(principal: Principal, sessionId: string, agentPreset: string): Promise<string>;
-  createSessionInWorkspace(principal: Principal, workspaceId: string, options: {
-    sessionId?: string;
-    agentPreset?: string;
-  }): Promise<{
-    id: string;
-    agentPreset?: string;
+interface SessionControllerLike {
+  list(request: {
+    cursor?: string;
+  }, signal: AbortSignal): Promise<{
+    items: readonly unknown[];
   }>;
-  createSession(principal: Principal, rootId: string, relativePath: string, options: {
+  create(request: {
+    workspaceId?: string;
+    cwd?: string;
     sessionId?: string;
     agentPreset?: string;
   }): Promise<{
-    id: string;
+    sessionId: string;
     agentPreset?: string;
   }>;
-  history(principal: Principal, sessionId: string, options: {
-    beforeSeq?: number;
+  /**
+   * Live follow stream. Its first frame is always a `snapshot` carrying the
+   * opening window (`cursor`, `records`, `hasMore`), and that is the only
+   * reliable way to read history: `page()` demands a `throughSeq` "obtained from
+   * the corresponding follow opening frame", so guessing one (e.g. `-1`) returns
+   * a well-formed but *empty* page — a silent failure, not an error.
+   */
+  follow(request: {
+    address: {
+      kind: 'session';
+      sessionId: string;
+    };
     maxMessages?: number;
-  }): Promise<{
-    events: unknown[];
-    hasMore: boolean;
-    projections?: unknown;
+    /**
+     * Assistant presentation frames are opt-in: without `assistantStream: true`
+     * the host emits durable events only, so a live stream would carry no
+     * incremental text at all (the transcript then appears only after commit).
+     */
+    assistantStream?: true;
+  }, signal: AbortSignal): AsyncIterable<{
+    type?: string;
+    cursor?: number;
+    records?: readonly unknown[];
+    hasMore?: boolean;
+  }>;
+  prompt(request: {
+    requestId: string;
+    sessionId: string;
+    mode: 'queue' | 'steer';
+    content: readonly PromptContentPartLike[];
+    clientTimeZone?: string;
+  }, signal: AbortSignal): Promise<{
+    accepted: true;
   }>;
-  prompt(principal: Principal, sessionId: string, parts: PromptContentPart[], mode: 'queue' | 'steer', clientTimeZone?: string): Promise<{
+  cancel(request: {
+    sessionId: string;
+  }): {
     accepted: true;
-    command?: unknown;
+  };
+  rename(request: {
+    sessionId: string;
+    title: string;
+  }): Promise<{
+    title: string;
+    seq: number;
+  }>;
+  fork(request: {
+    sessionId: string;
+    atSeq?: number;
+  }): Promise<{
+    sessionId: string;
   }>;
   /**
-   * 上传一个附件，返回 prompt 可以引用的凭证。
+   * 取一张**被这个会话引用过**的图片字节（内核主机端方法，名字就叫 `attachment`）。
    *
-   * 为什么需要这一步而不是让客户端直接把字节塞进消息：内核对**文件**类型要求的是
-   * `receiptId`（由上传换取），只有**图片**才允许内联 base64。
+   * 这是取历史图片的**正路**，它内部一次做完三件事：校验会话确实引用了这张图、
+   * 调 `ctx.attachments.readImage`、用**会话事件里那条真实 ref**做完整性校验
+   *（`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+   *
+   * 为什么必须走它、不能自己调 `ctx.attachments`：实测本机这条 profile 里
+   * `ctx.attachments` 是 **MISSING**（诊断日志
+   * `ctx.attachments MISSING（所以改走内核 sessionController.readAttachment）`），
+   * 自己拼 ref 那条路根本走不通；而且绕开内核就得把它内部三件事全复刻一遍，
+   * 早先正是只传了 id、缺四项元数据，导致 `ATTACHMENT_CORRUPT`。
+   *
+   * 注意方法名：**主机端叫 `attachment`**，客户端契约里才叫 `readAttachment`
+   *（`dsh-api-session-controller/lib/types/client/contract/session.d.ts`）。
+   * `data` 是 **base64 字符串**（主机端实现里 `Buffer.from(stored.data).toString("base64")`），
+   * 不是 Uint8Array —— 调用方要自己解码。
    */
-  uploadAttachment(principal: Principal, sessionId: string, data: string, name?: string): Promise<{
-    receiptId: string;
-    name: string | null;
+  attachment(request: {
+    sessionId: string;
+    attachmentId: string;
+  }): Promise<{
+    attachment: {
+      mediaType: string;
+    };
+    data: string;
+  }>;
+  selectModel(request: {
+    sessionId: string;
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+  }): Promise<{
+    selected: unknown;
   }>;
   /**
-   * 取回会话历史里某个图片附件的字节。
-   *
-   * **为什么会走内核的 `sessionController.attachment()`，而不自己调
-   * `ctx.attachments.readImage()`**：
-   * 1. 实测本机 profile 里 `ctx.attachments` 是 **MISSING**（拿不到注入属性）——
-   *    自己拼 ref 那条路根本走不通；
-   * 2. 内核那个方法内部一次做完三件事：校验该会话确实引用了这张图、
-   *    读出字节、用**会话事件里那条真实 ref** 做完整性校验
-   *    （`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
-   *    绕开它就得把这三件事全复刻 —— 先前正是漏了第三件，于是每张图
-   *    `ATTACHMENT_CORRUPT`：「字节读到了，却被校验拒之门外」。
-   *
-   * 因此 **sessionId 是必需参数**（内核要拿它读会话事件、找到那张图的真实 ref）；
-   * 早先设计的「客户端把四项元数据带上来」是多余的 —— 内核手里本来就有。
+   * Host model catalog. 0.2.x reports `default`, the routable route list, and
+   * per-route failures; the plugin's `SessionModelsView` instead wants a boolean
+   * `routable` plus a per-session `current`, so the bridge folds them (see the
+   * `models` method) rather than passing this through.
    */
-  readAttachment(principal: Principal, sessionId: string, attachmentId: string): Promise<{
-    bytes: Uint8Array;
-    mediaType: string;
+  modelCatalog(): Promise<{
+    default?: unknown;
+    routableProviders?: readonly string[];
+    groups?: readonly unknown[];
+    failures?: readonly {
+      id?: unknown;
+      name?: unknown;
+      message?: unknown;
+    }[];
   }>;
   /**
-   * 取回一张**交接图片**（纯文本模型发图时落在工作区 `.dsh-images/` 的那份）。
-   * 与 [readAttachment] 同样要求会话归属；文件名在桥里还有一道白名单校验。
+   * Projection baseline for one session. Unlike the catalog this is per-session,
+   * which is what makes it the source of the session's *current* model selection
+   * (`values.modelSelection`).
    */
-  readHandoffImage(principal: Principal, sessionId: string, name: string): Promise<{
-    bytes: Uint8Array;
-    mediaType: string;
+  projections(request: {
+    sessionId: string;
+  }, signal: AbortSignal): Promise<{
+    asOfSeq?: number;
+    values?: Record<string, unknown>;
+  } | null>;
+  resolveAgent(sessionId: string): Promise<unknown>;
+}
+interface WorkspaceControllerLike {
+  create(request: {
+    path: string;
+  }): Promise<{
+    workspace: unknown;
+    created: boolean;
   }>;
-  cancel(principal: Principal, sessionId: string): Promise<void>;
-  renameSession(principal: Principal, sessionId: string, title: string): Promise<{
+  rename(request: {
+    workspaceId: string;
     title: string;
-    seq: number;
+  }): Promise<unknown>;
+  delete(request: {
+    workspaceId: string;
+  }): Promise<{
+    deleted: boolean;
   }>;
-  forkSession(principal: Principal, sessionId: string, atSeq?: number): Promise<string>;
-  archiveSession(principal: Principal, sessionId: string): Promise<string[]>;
-  listPendingApprovals(principal: Principal, sessionId: string): Promise<PendingApprovalView[]>;
-  decideApproval(principal: Principal, sessionId: string, approvalId: string, outcome: 'allowed-once' | 'rejected'): Promise<PendingApprovalView>;
+  archiveSession(request: {
+    sessionId: string;
+  }): Promise<{
+    archivedSessionIds: readonly string[];
+  }>;
+}
+interface WorkspaceRegistryLike {
+  list(): readonly {
+    id: string;
+    path: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    sessionIds?: readonly string[];
+  }[];
+}
+interface SettingsControllerLike {
+  describe(): {
+    writable: boolean;
+    hasDocument: boolean;
+    namespaces: readonly unknown[];
+  };
+  mutate(ns: string, ops: readonly unknown[], expectedRevision: number | undefined): Promise<unknown>;
+}
+interface CredentialsControllerLike {
+  describe(refs: readonly string[]): Promise<Record<string, unknown>>;
+  set(ref: string, value: string): Promise<void>;
+  unset(ref: string): Promise<void>;
+}
+interface AgentPresetsLike {
+  list(): Promise<readonly unknown[]>;
+  remoteExportList(): Promise<unknown>;
+  resolveAgent?: never;
+  select(agent: unknown, agentPreset: string): Promise<string>;
+}
+interface LlmLike {
+  /** Live routes, as `{ id, name }` rows. */
+  listProviders(): readonly {
+    id: string;
+  }[];
+  /**
+   * Every route an adapter plugin could activate through configuration, live or
+   * dormant, carrying the settings namespace and path that configures it.
+   * Configuration surfaces merge this with `listProviders()` for liveness.
+   */
+  listConfigurableProviders(): readonly {
+    provider: string;
+    displayName: string;
+    settingsNs: string;
+    settingsPath: readonly string[];
+    declared?: boolean;
+    error?: string;
+  }[];
+  discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
   /**
-   * 列出「agent 正在等、且还能回答」的用户问题。
+   * 一个路由 + 模型 id 的**真实元数据**。
    *
-   * 口径与 [listPendingApprovals] 一致：先 requireSession（会话对本设备不可见 → 404），
-   * 再问内核；字段一个都不裁 —— 客户端照着渲染，内核加字段不用改插件。
+   * 为什么必须用它、而不是自己猜模型能不能看图：内核拒绝「给纯文本模型发图片」时
+   * 用的就是**这个方法**（`SessionController` 的 prompt 准入里
+   * `this.ctx.llm.resolveModelInfo(...)` 再查 `inputModalities`）。入口要与内核
+   * 得出同一个结论，只能查同一份元数据 —— 名字、前缀、家族表都是启发式，会漂。
    */
-  listUserQuestions(principal: Principal, sessionId: string): Promise<UserQuestionView[]>;
+  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
+    inputModalities?: readonly string[];
+  } | undefined>;
+}
+/** Host services the bridge consumes; assembled by `src/index.ts` from `ctx`. */
+interface Dsh02HostServices {
+  sessionController: SessionControllerLike;
+  workspaceController: WorkspaceControllerLike;
+  workspaceRegistry: WorkspaceRegistryLike;
+  settingsController: SettingsControllerLike;
+  credentialsController: CredentialsControllerLike;
+  agentPresets: AgentPresetsLike;
+  llm: LlmLike;
   /**
-   * 把一次答案提交给内核。
+   * 内核附件存储（`ctx.attachments`）；会话历史里的图片要经它取字节。
    *
-   * 失败原因全部由 `api.userQuestions.answer` 以**值**给出（见 [UserQuestionAnswerOutcome]），
-   * 这里翻成 HTTP 语义：503 能力缺失 / 409 状态冲突 / 400 批次不合法。
-   * 为什么不在 bridge 里直接抛：`unwrapDsh` 只把 `not-found` / `busy` / `locked`
-   * 映成 404/409，其余一律 400 —— 表达不了这几种区别。
+   * 必须是**已经取到的服务对象**，不能是 `ctx` 本身：cordis 的注入属性是有生命周期的
+   * 惰性访问器，只在 `apply` 执行期间可读。把它存进 `host` 里、等到 HTTP 请求回调
+   * （`readAttachment`）里再读，就会撞上
+   * `cannot get property "attachments" without inject` —— 请求链路本身没问题，
+   * 挂在服务端、而且只在真的去取图时才炸，所以很难在本地测出来。
    */
-  answerUserQuestion(principal: Principal, sessionId: string, callId: string, answer: UserQuestionAnswer): Promise<void>;
-  models(principal: Principal, sessionId: string): Promise<SessionModelsView>;
-  selectModel(principal: Principal, sessionId: string, selection: ModelSelectionView): Promise<ModelSelectionView>;
-  listCommands(principal: Principal, sessionId: string): Promise<CommandDescriptorView[]>;
-  executeCommand(principal: Principal, sessionId: string, line: string): Promise<CommandExecutionView>;
-  isSessionAuthorized(principal: Principal, sessionId: string): Promise<boolean>;
-  startEvents(signal: AbortSignal, emit: (event: WorkspaceEvent) => void): void;
-  private captureApproval;
-  private hasPendingApproval;
+  attachments: AttachmentStoreLike;
   /**
-   * Resolve the Agent backing a session for command work.
+   * Kernel file-upload service (`ctx.fileUploads`).
    *
-   * Returns `undefined` when the session exists but cannot be activated. 0.2.x
-   * rejects activation for a Session owned by a subagent, so that outcome is a
-   * property of the session rather than a failure of this call: the caller
-   * decides whether it means "no commands" (listing) or an error (execution).
+   * 为什么用它而不是内核那条 `/api/session/uploadFileBinary` HTTP 路由：那条路由
+   * 只绑 loopback（手机根本到不了），而这个 cordis 服务就在同一个进程里，插件可直接调。
    */
-  private commandAgent;
-  private requireSession;
-  private requireWorkspace;
-  private visibleWorkspaces;
-  private requireAuthorizedRoot;
-  private authorizedRoots;
-  private sessionRootId;
+  fileUploads: FileUploadsLike;
+  /**
+   * Cordis event bus of the host context. Used for the two facts the old
+   * `apiProxy` event streams carried that no controller returns: session
+   * registry changes and the approval answerer waterfall.
+   */
+  on(event: string, listener: (...args: any[]) => unknown): () => void;
 }
+/**
+ * 需要交接时，把每个 `image` 部件换成**两行文本**；否则原样返回。
+ *
+ * 同一行路径要同时伺候两类读者：
+ * - **给人看**（第一行）：图片序号、原始文件名、工作目录里的短路径；
+ * - **给机器看**（第二行 `[Image: source: <绝对路径>]`）：这是读图技能明确
+ *   识别的占位形状之一（带图片扩展名的绝对路径同样触发），任何按路径读图的
+ *   工具都能接手，不出现任何具体插件名。
+ *
+ * 任何一步抛错都退回原内容：这个功能的失败**不该**把「发消息」本身弄坏。
+ */
+/**
+ * 交接文案用哪种语言。
+ *
+ * 判据是**发消息那个客户端的界面语言**，由 HTTP `Accept-Language` 头带进来
+ * （router → chat-adapter → 这里）。拿不到就退回中文 —— 那是这个功能既有的默认口径，
+ * 判断不出来的时候不该突然换语言。
+ */
+type HandoffLocale = 'zh' | 'en';
 //#endregion
-//#region src/host/settings-adapter.d.ts
-interface SettingsNamespaceView {
-  ns: string;
-  schema?: unknown;
-  value: unknown;
-  base?: unknown;
-  user?: unknown;
-  revision: number;
-}
-interface ConfigurableProvider {
-  provider: string;
-  displayName: string;
-  settingsNs: string;
-  settingsPath: string[];
-  active: boolean;
-  declared?: boolean;
+//#region src/host/chat-adapter.d.ts
+interface RpcResponse<T> {
+  result: {
+    ok: true;
+    value: T;
+  } | {
+    ok: false;
+    error: {
+      code: string;
+      message: string;
+      details?: unknown;
+    };
+  };
 }
-interface SettingsApiProxy extends DshApiProxy {
-  settings: {
-    describe(request: {
+/**
+ * 一条 prompt 的内容片段 —— 与 DSH 0.2.x 的 `PromptContentPart` 一一对应。
+ *
+ * 三种形态的代价差别很大，值得写清楚：
+ * - `text`  直接发送；
+ * - `image` 字节**内联**在 payload 里（base64），一次调用完成，但请求体膨胀约 33%，
+ *   所以客户端必须先限制原图大小，别等 413；
+ * - `file`  的 `receiptId` 必须来自**先前的**上传调用，并在同一次 prompt 里绑定，
+ *   否则凭证会被回收。
+ */
+type PromptContentPart = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'image';
+  mediaType: string;
+  data: string;
+  name?: string;
+} | {
+  type: 'file';
+  receiptId: string;
+};
+interface DshApiProxy {
+  respond(message: {
+    type: 'client-response';
+    rpcId: string;
+    result: {
+      ok: true;
+      value: unknown;
+    };
+  }): Promise<{
+    accepted: true;
+  } | {
+    accepted: false;
+    reason: 'not-pending' | 'bad-response';
+  }>;
+  sessions: {
+    list(request: {
+      rpcId: string;
+      payload: {
+        cursor?: string;
+      };
+    }): Promise<RpcResponse<{
+      items: DshSessionSummary[];
+    }>>;
+    create(request: {
+      rpcId: string;
+      payload: {
+        cwd?: string;
+        workspaceId?: string;
+        sessionId?: string;
+        agentPreset?: string;
+      };
+    }): Promise<RpcResponse<{
+      sessionId: string;
+      agentPreset?: string;
+    }>>;
+    history(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        beforeSeq?: number;
+        maxMessages?: number;
+      };
+    }): Promise<RpcResponse<{
+      events: unknown[];
+      hasMore: boolean;
+      projections?: unknown;
+    }>>;
+    /**
+     * 提交一条 prompt。
+     *
+     * `locale` 不是内核字段，是**我们**加的：告诉图片交接「发消息的客户端界面是什么语言」，
+     * 好让交接说明说用户看得懂的话。它会一直传到 `dsh-0.2-bridge` 并在调内核前被摘掉。
+     */
+    prompt(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        mode: 'queue' | 'steer';
+        content: PromptContentPart[];
+        clientTimeZone?: string;
+        locale?: HandoffLocale;
+      };
+    }): Promise<RpcResponse<{
+      accepted: true;
+      command?: unknown;
+    }>>;
+    /**
+     * 上传一个文件，换取 prompt 可引用的凭证（`receiptId`）。
+     * `data` 是文件字节的**标准 base64**。
+     */
+    uploadAttachment(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        data: string;
+        name?: string;
+      };
+    }): Promise<RpcResponse<{
+      receiptId: string;
+      name: string | null;
+    }>>;
+    /**
+     * 按 id 取回附件字节。
+     *
+     * `attachmentId` 形如 `sha256:<hex>`（**含冒号**，客户端必须 URL 编码）。
+     * 返回 `Uint8Array` 而不是 base64：图片动辄上百 KB，多一次编解码纯属浪费。
+     *
+     * **必须带 `sessionId`**：内核要靠它读会话事件、取出这张图的真实 ref，
+     * 再据此做完整性校验（详见 chat-adapter 的 readAttachment 注释）。
+     */
+    readAttachment(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        attachmentId: string;
+      };
+    }): Promise<RpcResponse<{
+      bytes: Uint8Array;
+      mediaType: string;
+    }>>;
+    /**
+     * 取回一张**交接图片**的字节（纯文本模型发图时，图片被落成工作区文件）。
+     *
+     * 与 [readAttachment] 的区别：那一个取内核附件存储里的图（走
+     * `sessionController.attachment`），这一个取插件自己写进 `.dsh-images/`
+     * 的交接件。手机端用它把图片**显示**给人看；消息里的路径文本照旧留给模型。
+     */
+    readHandoffImage(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        name: string;
+      };
+    }): Promise<RpcResponse<{
+      bytes: Uint8Array;
+      mediaType: string;
+    }>>;
+    cancel(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+      };
+    }): Promise<RpcResponse<{
+      accepted: true;
+    }>>;
+    rename(request: {
       rpcId: string;
-      payload: Record<string, never>;
+      payload: {
+        sessionId: string;
+        title: string;
+      };
     }): Promise<RpcResponse<{
-      writable: boolean;
-      hasDocument: boolean;
-      namespaces: SettingsNamespaceView[];
+      title: string;
+      seq: number;
     }>>;
-    mutate(request: {
+    fork(request: {
       rpcId: string;
       payload: {
-        ns: string;
-        ops: Array<{
-          op: 'set';
-          path: string[];
-          value: unknown;
-        } | {
-          op: 'unset';
-          path: string[];
-        }>;
-        expectedRevision?: number;
+        sessionId: string;
+        atSeq?: number;
       };
-    }): Promise<RpcResponse<SettingsNamespaceView>>;
+    }): Promise<RpcResponse<{
+      sessionId: string;
+    }>>;
+    models(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+      };
+    }): Promise<RpcResponse<SessionModelsView>>;
+    selectModel(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+      };
+    }): Promise<RpcResponse<{
+      selected: ModelSelectionView;
+    }>>;
   };
-  credentials: {
-    describe(request: {
+  workspace: {
+    list(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }): Promise<RpcResponse<{
+      items: DshWorkspaceSummary[];
+      archivedSessionIds: string[];
+    }>>;
+    create(request: {
       rpcId: string;
       payload: {
-        refs: string[];
+        path: string;
       };
     }): Promise<RpcResponse<{
-      credentials: Record<string, {
-        configured: boolean;
-        source?: string;
-        writable: boolean;
-      }>;
+      workspace: DshWorkspaceSummary;
+      created: boolean;
     }>>;
-    set(request: {
+    rename(request: {
       rpcId: string;
       payload: {
-        ref: string;
-        value: string;
+        workspaceId: string;
+        title: string;
       };
-    }): Promise<RpcResponse<Record<string, never>>>;
-    unset(request: {
+    }): Promise<RpcResponse<{
+      workspace: DshWorkspaceSummary;
+    }>>;
+    delete(request: {
       rpcId: string;
       payload: {
-        ref: string;
+        workspaceId: string;
       };
-    }): Promise<RpcResponse<Record<string, never>>>;
+    }): Promise<RpcResponse<{
+      deleted: true;
+    }>>;
+    archiveSession(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+      };
+    }): Promise<RpcResponse<{
+      archivedSessionIds: string[];
+    }>>;
   };
-  llm: {
-    providers(request: {
+  agentPresets: {
+    list(request: {
       rpcId: string;
       payload: Record<string, never>;
     }): Promise<RpcResponse<{
-      providers: ConfigurableProvider[];
+      presets: DshAgentPresetSummary[];
+      authorable: boolean;
+      hasDocument: boolean;
     }>>;
-    models(request: {
+    select(request: {
       rpcId: string;
-      payload: Record<string, never>;
+      payload: {
+        sessionId: string;
+        agentPreset: string;
+      };
     }): Promise<RpcResponse<{
-      groups: ModelProviderGroupView[];
-      failures: {
-        provider: string;
-        message: string;
-      }[];
+      agentPreset: string;
     }>>;
-    discoverModels(request: {
+  };
+  /**
+   * 用户问题（内核 `ctx.userQuestions`，即 ask_user_question 工具）。
+   *
+   * 为什么单开一个命名空间而不是塞进 `sessions`：它由**另一个内核服务**提供
+   * （`@deepseek-ai/dsh-user-questions`），在一条没装它的 profile 上是**可选能力** ——
+   * 分开之后，「这个能力不在」和「这个会话有问题」在类型上就分得开。
+   */
+  userQuestions: {
+    /**
+     * 列出还能回答的问题（内核 `continued(agent)`）。
+     * 没有 live agent、或没有该服务时返回空列表 —— 冷会话是常态，不该报错。
+     */
+    list(request: {
       rpcId: string;
       payload: {
-        settingsNs: string;
-        provider?: string;
-        baseURL?: string;
-        api?: string;
-        apiKey?: string;
+        sessionId: string;
       };
     }): Promise<RpcResponse<{
-      models: ProviderModelView[];
+      items: UserQuestionView[];
     }>>;
+    /** 提交答案；失败原因见 [UserQuestionAnswerOutcome]。 */
+    answer(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        callId: string;
+        answer: UserQuestionAnswer;
+      };
+    }): Promise<RpcResponse<UserQuestionAnswerOutcome>>;
+  };
+  events: {
+    mux(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }, signal: AbortSignal): AsyncIterable<{
+      rpcId: string;
+      payload: Record<string, unknown>;
+    }>;
+    host(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }, signal: AbortSignal): AsyncIterable<{
+      rpcId: string;
+      payload: Record<string, unknown>;
+    }>;
   };
 }
-interface ProviderModelView {
-  id: string;
-  name?: string;
-  contextWindow?: number;
-  maxTokens?: number;
-}
-interface ProviderConfigView {
-  baseURL?: string;
-  api?: string;
-  displayName?: string;
-  thinking?: string;
+interface ModelSelectionView {
+  provider: string;
+  model: string;
   reasoningEffort?: string;
-  models: ProviderModelView[];
-  modelsInherited?: boolean;
 }
-interface ProviderView {
+interface ModelReasoningView {
+  efforts: {
+    id: string;
+    name: string;
+    description?: string;
+  }[];
+  defaultEffort?: string;
+}
+interface ModelProviderGroupView {
   id: string;
-  displayName: string;
-  active: boolean;
-  declared?: boolean;
-  configurable: boolean;
-  configured: boolean;
-  removable: boolean;
-  credential: {
-    ref: string;
-    configured: boolean;
-    source?: string;
-    writable: boolean;
+  name: string;
+  models: {
+    id: string;
+    name: string;
+    description?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    reasoning?: ModelReasoningView;
+  }[];
+}
+interface SessionModelsView {
+  current: ModelSelectionView;
+  routable: boolean;
+  groups: ModelProviderGroupView[];
+  failures: {
+    provider: string;
+    message: string;
+  }[];
+}
+interface CommandDescriptorView {
+  name: string;
+  description: string;
+  input?: {
+    hint: string;
   };
-  config: ProviderConfigView;
 }
-interface ProviderPatch {
-  displayName?: string | null;
-  baseURL?: string | null;
-  api?: string | null;
-  apiKey?: string | null;
-  thinking?: string | null;
-  reasoningEffort?: string | null;
-  models?: ProviderModelView[];
-  expectedRevision?: number;
+interface CommandExecutionView {
+  commandId: string;
+  result: {
+    kind: 'success' | 'error';
+    text?: string;
+    sourceEventSeq?: number;
+  };
+}
+interface DshCommandRuntime {
+  list(agent: unknown): readonly CommandDescriptorView[];
+  execute(agent: unknown, line: string, signal: AbortSignal): Promise<CommandExecutionView | undefined>;
+}
+interface DshAgentRegistry {
+  get(sessionId: string): unknown | undefined;
+}
+interface DshCommandServices {
+  commands: DshCommandRuntime;
+  agents: DshAgentRegistry;
+}
+interface DshSessionSummary {
+  sessionId: string;
+  updatedAt: number;
+  running: boolean;
+  blank: boolean;
+  cwd?: string;
+  agentPreset?: string;
+  parentSessionId?: string;
+  origin?: 'subagent';
+  projections?: {
+    asOfSeq: number;
+    values: Record<string, unknown>;
+  };
 }
-interface CustomProviderCreate {
+interface DshWorkspaceSummary {
+  workspaceId: string;
+  path: string;
+  title: string;
+  sessionIds: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+interface DshAgentPresetSummary {
   id: string;
-  displayName?: string;
-  baseURL: string;
-  api: string;
-  apiKey?: string;
-  models: ProviderModelView[];
-  expectedRevision?: number;
+  trust: 'system' | 'user';
+  isDefault: boolean;
+  name?: string;
+  description?: string;
+  broken?: string;
 }
-interface CustomProviderCapability {
-  available: boolean;
-  protocols: string[];
-  revision?: number;
+interface ChatSessionView {
+  id: string;
+  rootId: string;
+  cwd: string;
+  updatedAt: number;
+  running: boolean;
+  blank: boolean;
+  title?: string;
+  workspaceId?: string;
+  workspaceTitle?: string;
+  agentPreset?: string;
+  parentSessionId?: string;
+  origin?: 'subagent';
+  pendingInteraction?: 'approval';
 }
-declare class DshSettingsAdapter {
-  private readonly api;
-  constructor(api: SettingsApiProxy);
-  listProviders(): Promise<{
-    writable: boolean;
-    revisionByNamespace: Record<string, number>;
-    customProvider: CustomProviderCapability;
-    providers: ProviderView[];
-  }>;
-  catalog(): Promise<{
-    groups: ModelProviderGroupView[];
-    failures: {
-      provider: string;
-      message: string;
-    }[];
-  }>;
-  updateProvider(providerId: string, patch: ProviderPatch): Promise<void>;
-  createProvider(input: CustomProviderCreate): Promise<void>;
-  removeProvider(providerId: string, expectedRevision?: number): Promise<void>;
-  discover(providerId: string, draft: {
-    baseURL?: string;
-    api?: string;
-    apiKey?: string;
-  }): Promise<ProviderModelView[]>;
-  private providerContext;
+interface PendingApprovalView {
+  id: string;
+  sessionId: string;
+  toolName: string;
+  reason?: string;
+  detail?: string;
+  risk: 'standard' | 'full-access';
+  requestedAt: number;
 }
-//#endregion
-//#region src/host/dsh-0.2-bridge.d.ts
-/**
- * Prompt content a 0.2.x Host accepts — mirrors its `PromptContentPart` union.
- *
- * 权威定义在 `chat-adapter.ts`（协议层），这里只是复用它，避免两处各写一遍
- * 然后悄悄漂移。
- */
-type PromptContentPartLike = PromptContentPart;
 /**
- * `ctx.fileUploads`：内核的文件上传服务。
+ * 一条「还能回答」的用户问题 —— 内核 `userQuestions.continued()` 的一行。
  *
- * 由内核的 `@deepseek-ai/dsh-client-file-upload` 以 cordis 服务的形式暴露，
- * 因此插件**不需要**把字节转发到内核的 HTTP 路由（那条路由只绑 loopback，手机也到不了）。
+ * 为什么类型是宽松的、而不是照抄内核的 `AskUserQuestionItem`：内核往 item 或
+ * question 上加过字段（`intent` 就是一例），手机端该自己决定要不要用，
+ * 不该等插件跟着发版。所以这里只钉住三个**契约字段**，其余原样透传。
  */
-interface FileUploadsLike {
-  upload(agent: unknown, request: {
-    data: string;
-    name?: string;
-  }, signal: AbortSignal): Promise<{
-    receiptId: string;
-  }>;
-  /**
-   * 把凭证绑定到某次 prompt。返回值不 commit 的话凭证会被回收 ——
-   * 所以调用方必须在 prompt **成功之后** commit()。
-   */
-  bindPrompt(agent: unknown, receiptIds: readonly string[], requestId: string): {
-    commit(): void;
-  };
+interface UserQuestionView {
+  callId: string;
+  /** 内核 `UserQuestionState`：'open' 或 'continued'；本端点只返回 continued。 */
+  state: string;
+  /** 问题项**原样**透传（id / question / detail? / header? / options? / multiSelect? / intent?）。 */
+  questions: unknown[];
+  /** 内核以后加的字段照样透传，不在这里裁剪。 */
+  [key: string]: unknown;
+}
+/** 一条问题的答案（内核 `AskUserQuestionAnswerItem`）。 */
+interface UserQuestionAnswerItem {
+  /** 被回答的问题 id，必须与请求里的问题 id 对上。 */
+  id: string;
+  /** 选中的选项 label；多选时可能多项。 */
+  selected: string[];
+  /** 可选的「其他」自由文本。 */
+  custom?: string;
+}
+/** 一次提交的完整答案批次（内核 `AskUserQuestionAnswer`）：一次调用里的每个问题各占一项。 */
+interface UserQuestionAnswer {
+  answers: UserQuestionAnswerItem[];
 }
 /**
- * `ctx.attachments`：内核的附件存储。
+ * 「把答案送进内核」的结果。
  *
- * 为什么会话里的图片必须经由它：消息**发送时**图片是 base64 内联的，但**存进历史后**
- * 会变成 `{type:'image', attachment:{attachmentId:'sha256:…'}}` 这样的引用 ——
- * 字节在附件存储里，不在事件里。客户端只拿到 id，所以必须有一步「按 id 取字节」，
- * 否则历史里的图片一律显示不出来。
+ * 刻意**不走 RpcResponse 的 error 通道**：`unwrapDsh` 只认 `not-found` /
+ * `busy` / `locked` 三种 code 去映射 HTTP 状态，其余一律 400 —— 而这里需要区分
+ * 409 / 400 / 503。做成**值**之后由 adapter 决定 HTTP 状态，
+ * 和 approvals 的 `respond()` 返回 `{ accepted: false, reason }` 是同一个套路。
  */
-interface AttachmentStoreLike {
-  readImage(
-  /**
-   * 附件引用。
-   *
-   * `attachmentId` 是唯一的**定位**字段（内核用 `ID_PATTERN.exec()` 取出 sha256
-   * 再拼 `objects/<前两位>/<sha>`）；而 `mediaType` / `bytes` / `width` / `height`
-   * 参与读后**完整性校验** —— 缺任何一项都会抛 `ATTACHMENT_CORRUPT`，
-   * 哪怕字节已经正确读出来了。
-   */
-  ref: {
-    attachmentId: string;
-    mediaType?: string;
-    bytes?: number;
-    width?: number;
-    height?: number;
-  }, signal?: AbortSignal): Promise<{
-    ref: {
-      mediaType: string;
-    };
-    data: Uint8Array;
-  }>;
+type UserQuestionAnswerFailure =
+/** 内核里没有这个 callId 的悬空问题（`answer()` 返回了 false）。 */
+'not-pending' |
+/** 已经有一条回复在排队（内核 `REPLY_QUEUED`）。重复提交不是服务器故障。 */
+'reply-queued' |
+/** 答案批次没有「一问一答」地对齐（内核 `BAD_ANSWER`）。 */
+'answer-invalid' |
+/** 这个 agent 现在不接受人工回答（非 live root / 被别的 agent 拥有），或会话没有 live agent。 */
+'not-answerable' |
+/** 这套 DSH 构建里压根没有 `ctx.userQuestions` 服务。 */
+'unavailable';
+type UserQuestionAnswerOutcome = {
+  accepted: true;
+} | {
+  accepted: false;
+  reason: UserQuestionAnswerFailure;
+};
+interface ChatWorkspaceView {
+  id: string;
+  title: string;
+  rootId: string;
+  path: string;
+  createdAt: string;
+  updatedAt: string;
 }
-interface SessionControllerLike {
-  list(request: {
-    cursor?: string;
-  }, signal: AbortSignal): Promise<{
-    items: readonly unknown[];
-  }>;
-  create(request: {
-    workspaceId?: string;
-    cwd?: string;
+interface AgentPresetView {
+  id: string;
+  name: string;
+  description?: string;
+  trust: 'system' | 'user';
+  isDefault: boolean;
+  available: boolean;
+}
+declare class DshChatAdapter {
+  private readonly api;
+  private readonly database;
+  private readonly commandServices?;
+  private readonly sessionRootIds;
+  private readonly sessionRootLookups;
+  private readonly pendingApprovals;
+  constructor(api: DshApiProxy, database: WorkspaceDatabase, commandServices?: DshCommandServices | undefined);
+  listSessions(principal: Principal): Promise<ChatSessionView[]>;
+  listWorkspaces(principal: Principal): Promise<ChatWorkspaceView[]>;
+  createWorkspace(principal: Principal, rootId: string, relativePath: string): Promise<ChatWorkspaceView>;
+  renameWorkspace(principal: Principal, workspaceId: string, title: string): Promise<ChatWorkspaceView>;
+  deleteWorkspace(principal: Principal, workspaceId: string): Promise<void>;
+  listAgentPresets(): Promise<AgentPresetView[]>;
+  selectAgentPreset(principal: Principal, sessionId: string, agentPreset: string): Promise<string>;
+  createSessionInWorkspace(principal: Principal, workspaceId: string, options: {
     sessionId?: string;
     agentPreset?: string;
   }): Promise<{
-    sessionId: string;
-    agentPreset?: string;
-  }>;
-  /**
-   * Live follow stream. Its first frame is always a `snapshot` carrying the
-   * opening window (`cursor`, `records`, `hasMore`), and that is the only
-   * reliable way to read history: `page()` demands a `throughSeq` "obtained from
-   * the corresponding follow opening frame", so guessing one (e.g. `-1`) returns
-   * a well-formed but *empty* page — a silent failure, not an error.
-   */
-  follow(request: {
-    address: {
-      kind: 'session';
-      sessionId: string;
-    };
-    maxMessages?: number;
-    /**
-     * Assistant presentation frames are opt-in: without `assistantStream: true`
-     * the host emits durable events only, so a live stream would carry no
-     * incremental text at all (the transcript then appears only after commit).
-     */
-    assistantStream?: true;
-  }, signal: AbortSignal): AsyncIterable<{
-    type?: string;
-    cursor?: number;
-    records?: readonly unknown[];
-    hasMore?: boolean;
-  }>;
-  prompt(request: {
-    requestId: string;
-    sessionId: string;
-    mode: 'queue' | 'steer';
-    content: readonly PromptContentPartLike[];
-    clientTimeZone?: string;
-  }, signal: AbortSignal): Promise<{
-    accepted: true;
+    id: string;
+    agentPreset?: string;
   }>;
-  cancel(request: {
-    sessionId: string;
-  }): {
-    accepted: true;
-  };
-  rename(request: {
-    sessionId: string;
-    title: string;
+  createSession(principal: Principal, rootId: string, relativePath: string, options: {
+    sessionId?: string;
+    agentPreset?: string;
   }): Promise<{
-    title: string;
-    seq: number;
+    id: string;
+    agentPreset?: string;
   }>;
-  fork(request: {
-    sessionId: string;
-    atSeq?: number;
+  history(principal: Principal, sessionId: string, options: {
+    beforeSeq?: number;
+    maxMessages?: number;
   }): Promise<{
-    sessionId: string;
+    events: unknown[];
+    hasMore: boolean;
+    projections?: unknown;
+  }>;
+  prompt(principal: Principal, sessionId: string, parts: PromptContentPart[], mode: 'queue' | 'steer', clientTimeZone?: string, locale?: HandoffLocale): Promise<{
+    accepted: true;
+    command?: unknown;
   }>;
   /**
-   * 取一张**被这个会话引用过**的图片字节（内核主机端方法，名字就叫 `attachment`）。
-   *
-   * 这是取历史图片的**正路**，它内部一次做完三件事：校验会话确实引用了这张图、
-   * 调 `ctx.attachments.readImage`、用**会话事件里那条真实 ref**做完整性校验
-   *（`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
-   *
-   * 为什么必须走它、不能自己调 `ctx.attachments`：实测本机这条 profile 里
-   * `ctx.attachments` 是 **MISSING**（诊断日志
-   * `ctx.attachments MISSING（所以改走内核 sessionController.readAttachment）`），
-   * 自己拼 ref 那条路根本走不通；而且绕开内核就得把它内部三件事全复刻一遍，
-   * 早先正是只传了 id、缺四项元数据，导致 `ATTACHMENT_CORRUPT`。
+   * 上传一个附件，返回 prompt 可以引用的凭证。
    *
-   * 注意方法名：**主机端叫 `attachment`**，客户端契约里才叫 `readAttachment`
-   *（`dsh-api-session-controller/lib/types/client/contract/session.d.ts`）。
-   * `data` 是 **base64 字符串**（主机端实现里 `Buffer.from(stored.data).toString("base64")`），
-   * 不是 Uint8Array —— 调用方要自己解码。
+   * 为什么需要这一步而不是让客户端直接把字节塞进消息：内核对**文件**类型要求的是
+   * `receiptId`（由上传换取），只有**图片**才允许内联 base64。
    */
-  attachment(request: {
-    sessionId: string;
-    attachmentId: string;
-  }): Promise<{
-    attachment: {
-      mediaType: string;
-    };
-    data: string;
-  }>;
-  selectModel(request: {
-    sessionId: string;
-    provider: string;
-    model: string;
-    reasoningEffort?: string;
-  }): Promise<{
-    selected: unknown;
+  uploadAttachment(principal: Principal, sessionId: string, data: string, name?: string): Promise<{
+    receiptId: string;
+    name: string | null;
   }>;
   /**
-   * Host model catalog. 0.2.x reports `default`, the routable route list, and
-   * per-route failures; the plugin's `SessionModelsView` instead wants a boolean
-   * `routable` plus a per-session `current`, so the bridge folds them (see the
-   * `models` method) rather than passing this through.
+   * 取回会话历史里某个图片附件的字节。
+   *
+   * **为什么会走内核的 `sessionController.attachment()`，而不自己调
+   * `ctx.attachments.readImage()`**：
+   * 1. 实测本机 profile 里 `ctx.attachments` 是 **MISSING**（拿不到注入属性）——
+   *    自己拼 ref 那条路根本走不通；
+   * 2. 内核那个方法内部一次做完三件事：校验该会话确实引用了这张图、
+   *    读出字节、用**会话事件里那条真实 ref** 做完整性校验
+   *    （`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+   *    绕开它就得把这三件事全复刻 —— 先前正是漏了第三件，于是每张图
+   *    `ATTACHMENT_CORRUPT`：「字节读到了，却被校验拒之门外」。
+   *
+   * 因此 **sessionId 是必需参数**（内核要拿它读会话事件、找到那张图的真实 ref）；
+   * 早先设计的「客户端把四项元数据带上来」是多余的 —— 内核手里本来就有。
    */
-  modelCatalog(): Promise<{
-    default?: unknown;
-    routableProviders?: readonly string[];
-    groups?: readonly unknown[];
-    failures?: readonly {
-      id?: unknown;
-      name?: unknown;
-      message?: unknown;
-    }[];
+  readAttachment(principal: Principal, sessionId: string, attachmentId: string): Promise<{
+    bytes: Uint8Array;
+    mediaType: string;
   }>;
   /**
-   * Projection baseline for one session. Unlike the catalog this is per-session,
-   * which is what makes it the source of the session's *current* model selection
-   * (`values.modelSelection`).
+   * 取回一张**交接图片**（纯文本模型发图时落在工作区 `.dsh-images/` 的那份）。
+   * 与 [readAttachment] 同样要求会话归属；文件名在桥里还有一道白名单校验。
    */
-  projections(request: {
-    sessionId: string;
-  }, signal: AbortSignal): Promise<{
-    asOfSeq?: number;
-    values?: Record<string, unknown>;
-  } | null>;
-  resolveAgent(sessionId: string): Promise<unknown>;
-}
-interface WorkspaceControllerLike {
-  create(request: {
-    path: string;
-  }): Promise<{
-    workspace: unknown;
-    created: boolean;
+  readHandoffImage(principal: Principal, sessionId: string, name: string): Promise<{
+    bytes: Uint8Array;
+    mediaType: string;
   }>;
-  rename(request: {
-    workspaceId: string;
+  cancel(principal: Principal, sessionId: string): Promise<void>;
+  renameSession(principal: Principal, sessionId: string, title: string): Promise<{
     title: string;
-  }): Promise<unknown>;
-  delete(request: {
-    workspaceId: string;
-  }): Promise<{
-    deleted: boolean;
-  }>;
-  archiveSession(request: {
-    sessionId: string;
-  }): Promise<{
-    archivedSessionIds: readonly string[];
+    seq: number;
   }>;
-}
-interface WorkspaceRegistryLike {
-  list(): readonly {
-    id: string;
-    path: string;
-    title: string;
-    createdAt: string;
-    updatedAt: string;
-    sessionIds?: readonly string[];
-  }[];
-}
-interface SettingsControllerLike {
-  describe(): {
-    writable: boolean;
-    hasDocument: boolean;
-    namespaces: readonly unknown[];
-  };
-  mutate(ns: string, ops: readonly unknown[], expectedRevision: number | undefined): Promise<unknown>;
-}
-interface CredentialsControllerLike {
-  describe(refs: readonly string[]): Promise<Record<string, unknown>>;
-  set(ref: string, value: string): Promise<void>;
-  unset(ref: string): Promise<void>;
-}
-interface AgentPresetsLike {
-  list(): Promise<readonly unknown[]>;
-  remoteExportList(): Promise<unknown>;
-  resolveAgent?: never;
-  select(agent: unknown, agentPreset: string): Promise<string>;
-}
-interface LlmLike {
-  /** Live routes, as `{ id, name }` rows. */
-  listProviders(): readonly {
-    id: string;
-  }[];
-  /**
-   * Every route an adapter plugin could activate through configuration, live or
-   * dormant, carrying the settings namespace and path that configures it.
-   * Configuration surfaces merge this with `listProviders()` for liveness.
-   */
-  listConfigurableProviders(): readonly {
-    provider: string;
-    displayName: string;
-    settingsNs: string;
-    settingsPath: readonly string[];
-    declared?: boolean;
-    error?: string;
-  }[];
-  discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
+  forkSession(principal: Principal, sessionId: string, atSeq?: number): Promise<string>;
+  archiveSession(principal: Principal, sessionId: string): Promise<string[]>;
+  listPendingApprovals(principal: Principal, sessionId: string): Promise<PendingApprovalView[]>;
+  decideApproval(principal: Principal, sessionId: string, approvalId: string, outcome: 'allowed-once' | 'rejected'): Promise<PendingApprovalView>;
   /**
-   * 一个路由 + 模型 id 的**真实元数据**。
+   * 列出「agent 正在等、且还能回答」的用户问题。
    *
-   * 为什么必须用它、而不是自己猜模型能不能看图：内核拒绝「给纯文本模型发图片」时
-   * 用的就是**这个方法**（`SessionController` 的 prompt 准入里
-   * `this.ctx.llm.resolveModelInfo(...)` 再查 `inputModalities`）。入口要与内核
-   * 得出同一个结论，只能查同一份元数据 —— 名字、前缀、家族表都是启发式，会漂。
+   * 口径与 [listPendingApprovals] 一致：先 requireSession（会话对本设备不可见 → 404），
+   * 再问内核；字段一个都不裁 —— 客户端照着渲染，内核加字段不用改插件。
    */
-  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
-    inputModalities?: readonly string[];
-  } | undefined>;
-}
-/** Host services the bridge consumes; assembled by `src/index.ts` from `ctx`. */
-interface Dsh02HostServices {
-  sessionController: SessionControllerLike;
-  workspaceController: WorkspaceControllerLike;
-  workspaceRegistry: WorkspaceRegistryLike;
-  settingsController: SettingsControllerLike;
-  credentialsController: CredentialsControllerLike;
-  agentPresets: AgentPresetsLike;
-  llm: LlmLike;
+  listUserQuestions(principal: Principal, sessionId: string): Promise<UserQuestionView[]>;
   /**
-   * 内核附件存储（`ctx.attachments`）；会话历史里的图片要经它取字节。
+   * 把一次答案提交给内核。
    *
-   * 必须是**已经取到的服务对象**，不能是 `ctx` 本身：cordis 的注入属性是有生命周期的
-   * 惰性访问器，只在 `apply` 执行期间可读。把它存进 `host` 里、等到 HTTP 请求回调
-   * （`readAttachment`）里再读，就会撞上
-   * `cannot get property "attachments" without inject` —— 请求链路本身没问题，
-   * 挂在服务端、而且只在真的去取图时才炸，所以很难在本地测出来。
+   * 失败原因全部由 `api.userQuestions.answer` 以**值**给出（见 [UserQuestionAnswerOutcome]），
+   * 这里翻成 HTTP 语义：503 能力缺失 / 409 状态冲突 / 400 批次不合法。
+   * 为什么不在 bridge 里直接抛：`unwrapDsh` 只把 `not-found` / `busy` / `locked`
+   * 映成 404/409，其余一律 400 —— 表达不了这几种区别。
    */
-  attachments: AttachmentStoreLike;
+  answerUserQuestion(principal: Principal, sessionId: string, callId: string, answer: UserQuestionAnswer): Promise<void>;
+  models(principal: Principal, sessionId: string): Promise<SessionModelsView>;
+  selectModel(principal: Principal, sessionId: string, selection: ModelSelectionView): Promise<ModelSelectionView>;
+  listCommands(principal: Principal, sessionId: string): Promise<CommandDescriptorView[]>;
+  executeCommand(principal: Principal, sessionId: string, line: string): Promise<CommandExecutionView>;
+  isSessionAuthorized(principal: Principal, sessionId: string): Promise<boolean>;
+  startEvents(signal: AbortSignal, emit: (event: WorkspaceEvent) => void): void;
+  private captureApproval;
+  private hasPendingApproval;
   /**
-   * Kernel file-upload service (`ctx.fileUploads`).
+   * Resolve the Agent backing a session for command work.
    *
-   * 为什么用它而不是内核那条 `/api/session/uploadFileBinary` HTTP 路由：那条路由
-   * 只绑 loopback（手机根本到不了），而这个 cordis 服务就在同一个进程里，插件可直接调。
-   */
-  fileUploads: FileUploadsLike;
-  /**
-   * Cordis event bus of the host context. Used for the two facts the old
-   * `apiProxy` event streams carried that no controller returns: session
-   * registry changes and the approval answerer waterfall.
+   * Returns `undefined` when the session exists but cannot be activated. 0.2.x
+   * rejects activation for a Session owned by a subagent, so that outcome is a
+   * property of the session rather than a failure of this call: the caller
+   * decides whether it means "no commands" (listing) or an error (execution).
    */
-  on(event: string, listener: (...args: any[]) => unknown): () => void;
+  private commandAgent;
+  private requireSession;
+  private requireWorkspace;
+  private visibleWorkspaces;
+  private requireAuthorizedRoot;
+  private authorizedRoots;
+  private sessionRootId;
 }
 //#endregion
 //#region src/host/rate-limit.d.ts
@@ -1322,6 +1445,13 @@ interface RouterOptions {
   settings: DshSettingsAdapter;
   remote: RemoteControl;
   maxUploadBytes: number;
+  /**
+   * 解析不出会话工作目录时的图片兜底目录（设置面板里只读展示）。
+   *
+   * 可选：默认按 `database.dataDir` 推出来，测试因此不必每条都补一个字段。
+   * 生产路径由 `index.ts` 传入与交接实际使用**同一个**目录，避免「界面显示 A、落盘在 B」。
+   */
+  imageFallbackDir?: string;
 }
 declare class ApiRouter {
   private readonly options;
@@ -1333,6 +1463,8 @@ declare class ApiRouter {
   private dispatchContent;
   private requireRoot;
   private authorizedRoots;
+  /** 兜底交接目录：没配就用状态目录下的 `image-handoff`（与 `index.ts` 的默认一致）。 */
+  private imageFallbackDir;
   private audit;
   private readIdempotent;
   private saveIdempotent;
@@ -1388,13 +1520,19 @@ declare class RemoteApiServer implements RemoteControl {
   private eventAllowed;
   private trimOperations;
 }
+/** 一条挂在 DSH webserver 上的插件自有路由。 */
+interface EmbeddedRoute {
+  kind: 'exact' | 'prefix';
+  path: string;
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
 declare function attachEmbeddedRoutes(webServer: {
   register(route: {
     kind: 'exact' | 'prefix';
     path: string;
     handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
   }): () => void;
-}, router: ApiRouter, remote: RemoteApiServer): () => void;
+}, router: ApiRouter, remote: RemoteApiServer, extraRoutes?: readonly EmbeddedRoute[]): () => void;
 //#endregion
 //#region src/index.d.ts
 /**