dsh-remote-bridge 2.4.1 → 2.4.3

package/lib/index.d.ts

@@ -655,6 +655,73 @@ interface AgentPresetsLike {
   resolveAgent?: never;
   select(agent: unknown, agentPreset: string): Promise<string>;
 }
+/**
+ * 内核 `dsh-permission-presets`（cordis 服务名 `permissionPresets`）。
+ *
+ * @patch
+ * id: permission-presets-catalog-bff
+ * for: 内核把「权限预设清单」放在**独立的远程服务**上（`@Remote('catalog')`），
+ *      而会话投影里那条同名 wire 视图只给 `currentValue`（`wire.view: state => ({ currentValue })`），
+ *      两者没有任何交叉引用。客户端要列候选档位就只能自己编。
+ * why: 没有正规写法可用 —— 内核的 Host FaceModel 里没有「把 catalog 并进投影」这个方法；
+ *      插件唯一的入口就是那个远程服务。
+ * until: 内核把候选项并进投影，或提供一条已含 options 的查询。
+ * test: tests/permission-presets.spec.ts
+ */
+interface PermissionPresetsLike {
+  catalog(): Promise<unknown>;
+}
+/**
+ * 内核 `dsh-api-job-controller`（cordis 服务名 `jobController`）。
+ *
+ * 后台任务（目前只有 bash 一种 producer kind）的只读观察 + 人类取消。
+ *
+ * **`list` 与 `follow` 是流，不是一次性查询** —— 内核类型上就是
+ * `AsyncIterable<JobListFrame>` / `AsyncIterable<JobFollowFrame>`。但 list 的首帧
+ * 就是全量 truth（内核注释原文：「Whole-set replacement, so a reconnect's first
+ * frame is already the truth」），所以 REST 侧读**第一帧**即可得到完整清单，
+ * 不必把 HTTP 变成长连接（手机端耗电、断线重连都更难）。
+ *
+ * 只有 `kill` 是同步的，且它的返回只有两种：`requested` / `already-finished`
+ * —— 没有「不存在」这一档，未知 job 走 `job/not-found` 远程错误。
+ *
+ * 结构类型照 `dsh-api-job-controller/lib/types/{index,types}.d.ts` 与
+ * `dsh-jobs/lib/types/view.d.ts` 抄，只留本插件真用到的那部分。
+ */
+interface JobControllerLike {
+  /** 流：首帧全量，随后每次生命周期提交后一帧。 */
+  list(request: {
+    sessionId: string;
+  }, signal: AbortSignal): AsyncIterable<{
+    type?: string;
+    jobs?: readonly unknown[];
+  }>;
+  /** 流：opened 锚点 → 若干 output 批次 → 终态 status，之后正常关闭。 */
+  follow(request: {
+    sessionId?: string;
+    jobId: string;
+    from?: number;
+  }, signal: AbortSignal): AsyncIterable<{
+    type?: string;
+    job?: unknown;
+    from?: number;
+    chunks?: readonly unknown[];
+    next?: number;
+    lossy?: true;
+  }>;
+  /**
+   * 人类取消。返回 `requested`（已受理）或 `already-finished`（已终态，无需再杀）。
+   *
+   * 注意它**不是** Promise：内核类型上就是同步返回。调用方 `await` 它也合法
+   * （await 非 Promise 返回原值），所以这里按内核原样声明成同步。
+   */
+  kill(request: {
+    sessionId: string;
+    jobId: string;
+  }): {
+    outcome: 'requested' | 'already-finished';
+  };
+}
 interface LlmLike {
   /** Live routes, as `{ id, name }` rows. */
   listProviders(): readonly {
@@ -694,6 +761,17 @@ interface Dsh02HostServices {
   settingsController: SettingsControllerLike;
   credentialsController: CredentialsControllerLike;
   agentPresets: AgentPresetsLike;
+  permissionPresets: PermissionPresetsLike;
+  /**
+   * 后台任务控制器（`ctx.jobController`，`@deepseek-ai/dsh-api-job-controller`）。
+   *
+   * 为什么要它：远程场景下「任务跑飞了停不掉」是真焦虑 —— 人不在电脑前，
+   * 一个卡住的 bash 任务只能干等。手机端需要能看到清单并终止它。
+   *
+   * 与 `sessionController` 不同，这个是 `TypertRemoteService`（不是 `@Remote`
+   * 控制器集合），但结构类型消费方式完全一样：只声明用到的成员，缺了就明确报错。
+   */
+  jobController: JobControllerLike;
   llm: LlmLike;
   /**
    * 内核附件存储（`ctx.attachments`）；会话历史里的图片要经它取字节。
@@ -1006,6 +1084,18 @@ interface DshApiProxy {
       agentPreset: string;
     }>>;
   };
+  /**
+   * 权限档位目录（内核 `ctx.permissionPresets`）。
+   *
+   * 单开命名空间的理由与 userQuestions 相同：它由**另一个内核服务**提供
+   * （`@deepseek-ai/dsh-permission-presets`），在没装它的 profile 上是可选能力。
+   */
+  permissionPresets: {
+    catalog(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }): Promise<RpcResponse<unknown>>;
+  };
   /**
    * 用户问题（内核 `ctx.userQuestions`，即 ask_user_question 工具）。
    *
@@ -1114,7 +1204,14 @@ interface CommandExecutionView {
 }
 interface DshCommandRuntime {
   list(agent: unknown): readonly CommandDescriptorView[];
-  execute(agent: unknown, line: string, signal: AbortSignal): Promise<CommandExecutionView | undefined>;
+  /**
+   * 内核签名是 **四个**参数：`execute(agent, line, submittedAttachments, signal)`。
+   *
+   * 少传一个（把 signal 传到第三个位）会让内核读到 `undefined.aborted`，
+   * 表现为**所有**斜杠命令都报 `Cannot read properties of undefined (reading 'aborted')`。
+   * 实测 2026-10-19 踩过：手机端因此切不了会话权限档位。
+   */
+  execute(agent: unknown, line: string, submittedAttachments: readonly unknown[], signal: AbortSignal): Promise<CommandExecutionView | undefined>;
 }
 interface DshAgentRegistry {
   get(sessionId: string): unknown | undefined;
@@ -1263,6 +1360,16 @@ interface AgentPresetView {
   isDefault: boolean;
   available: boolean;
 }
+/**
+ * 一个可选的权限档位。字段名刻意与内核 `optionOf()` 的产出一致
+ * （`{ value, name, description? }`），中间不再改名 —— 客户端的
+ * kotlinx.serialization 严格解码器对字段名敏感。
+ */
+interface PermissionOptionView {
+  value: string;
+  name: string;
+  description?: string;
+}
 declare class DshChatAdapter {
   private readonly api;
   private readonly database;
@@ -1293,6 +1400,16 @@ declare class DshChatAdapter {
   renameWorkspace(principal: Principal, workspaceId: string, title: string): Promise<ChatWorkspaceView>;
   deleteWorkspace(principal: Principal, workspaceId: string): Promise<void>;
   listAgentPresets(): Promise<AgentPresetView[]>;
+  /**
+   * 权限档位候选清单。
+   *
+   * 为什么这条必须在插件侧：BFF 要把内核的进程级 catalog 透出来。会话投影里那条
+   * wire 视图只带 `currentValue`，没有候选项 —— 客户端拿不到候选就列不出档位菜单。
+   */
+  listPermissionPresets(): Promise<{
+    options: PermissionOptionView[];
+    defaultPreset: string;
+  }>;
   selectAgentPreset(principal: Principal, sessionId: string, agentPreset: string): Promise<string>;
   createSessionInWorkspace(principal: Principal, workspaceId: string, options: {
     sessionId?: string;
@@ -1477,6 +1594,136 @@ declare class WorkspaceEventBus {
   subscribe(listener: (event: WorkspaceEvent) => void): () => void;
 }
 //#endregion
+//#region src/host/host-service-probe.d.ts
+interface ServiceProbe {
+  name: string;
+  /** 服务是否可解析。`false` = cordis 认为没有插件提供它。 */
+  available: boolean;
+  /** 解析失败时的错误信息（成功时为 undefined）。 */
+  error?: string;
+  /** 解析到的值是否像一个可用的服务对象（非 null/非 undefined）。 */
+  resolvable: boolean;
+}
+interface HostServiceReport {
+  /** 探针执行时的内核运行时版本，供比对「哪个版本注入面是这样」。 */
+  pluginVersion: string;
+  injected: ServiceProbe[];
+  observed: ServiceProbe[];
+  /** 注入面摘要：注入了几个、缺几个。缺的那几个就是「功能可能静默不工作」的清单。 */
+  summary: {
+    injectedTotal: number;
+    injectedAvailable: number;
+    injectedMissing: readonly string[];
+    observedAvailable: readonly string[];
+  };
+}
+//#endregion
+//#region src/host/job-adapter.d.ts
+/**
+ * 后台任务（background jobs）。
+ *
+ * ## 为什么需要它
+ *
+ * 远程场景下有个真焦虑：用户在手机上让 agent 跑个长任务（bash 构建、批量处理），
+ * 然后切到别的会话或者放下手机 —— **此时没有任何地方能看到「它还在跑吗」，
+ * 更没有地方能「让它停下」**。任务跑飞了只能干等，或者回到电脑前。
+ *
+ * 而内核一直有这套能力：`dsh-api-job-controller` 在 web profile 里挂着，
+ * 提供 roster 流（`list`）、单任务输出观察流（`follow`）与人类取消（`kill`）。
+ * 官方 WebUI 有 Jobs 面板（`client-ui-jobs` + `IconJobs`），本桥此前 26 个能力位里
+ * **一个 job 相关的都没有**。
+ *
+ * ## 为什么 REST 只读第一帧，不做长连接
+ *
+ * 内核的 `list` 是 `AsyncIterable<JobListFrame>`，但内核注释写得很清楚：
+ * 「Whole-set replacement, so a reconnect's first frame is already the truth」——
+ * **首帧就是完整真相**。所以：
+ *
+ * - REST `GET /jobs` 读第一帧就够，返回完整清单；
+ * - 不把 HTTP 变成长连接：手机端长连接耗电、断线重连复杂、而且清单本来就该「拉一次就是真的」；
+ * - 实时推送留给后续（若要，走 WebSocket 事件帧，与 chat.* 同一条通道）。
+ *
+ * ## 为什么端点挂在会话维度下
+ *
+ * 内核的 `list(request)` 与 `kill(request)` **都要 `sessionId`** —— 返回的是
+ * 「该会话自己的任务 + 所有无主任务」，owner fence 是唯一的访问规则。
+ * 所以本模块的每个方法都要调用方给出 `sessionId`，**不能替客户端猜** ——
+ * 猜错会让一个会话看到另一个会话的任务。`kill` 同理：请求里的 session 就是
+ * 那次围栏读写的调用者。
+ *
+ * 所以 REST 也必须是会话维度的：`/chat/sessions/{sessionId}/jobs`。
+ * 做成顶层 `/jobs` 就得让客户端额外猜一个 session，那是把内核的围栏语义
+ * 搬到桥外面，早晚出「一个会话看到另一个会话的任务」这种事。
+ *
+ * 可见性由内核裁决，本模块不二次判断：内核抛 `job/not-found` 就转成 404。
+ */
+/** 一个后台任务的对外视图（内核 `JobView` 的结构投影）。 */
+interface JobView {
+  id: string;
+  kind: string;
+  label: string;
+  /** 属主会话；无主任务没有这个字段（任何调用方都可见）。 */
+  owner?: string;
+  status: 'running' | 'stopping' | 'completed' | 'killed' | 'failed';
+  /** 生产者的实时进度行（`3/10`、当前阶段）；终态时被清空。 */
+  progress?: string;
+  /** 终态原因（`exit code: 3`）；记录过的 kill 原因会并进来。 */
+  detail?: string;
+  /** 注册时刻（epoch ms）。 */
+  startedAt: number;
+  /** 落定时刻（epoch ms）；存活中无此字段。 */
+  finishedAt?: number;
+}
+/** `GET /jobs` 的响应。 */
+interface JobListResult {
+  jobs: JobView[];
+}
+/** `POST /jobs/{jobId}/kill` 的响应。 */
+interface JobKillResult {
+  jobId: string;
+  /** `requested` = 已受理；`already-finished` = 已是终态，无需再杀。 */
+  outcome: 'requested' | 'already-finished';
+}
+declare class JobAdapter {
+  private readonly host;
+  constructor(host: {
+    jobController: JobControllerLike;
+  });
+  /**
+   * 列出某个会话可见的后台任务。
+   *
+   * 读流的**第一帧**（内核保证它是全量 truth）。若流首帧就不是 `rows`
+   * （内核升级改了帧型），明确报错而不是返回空清单 ——
+   * 空清单会被客户端理解成「没有任务」，那是**假的**。
+   */
+  list(sessionId: string, signal: AbortSignal): Promise<JobListResult>;
+  /**
+   * 读一个任务已保留的输出（从指定字节偏移继续）。
+   *
+   * 内核的 `follow` 是流：`opened` 锚点 → 若干 `output` 批次 → 终态 `status`。
+   * 这里**只读到第一个终态帧或流结束为止**，把批次摊平成一个文本块 ——
+   * 手机端要看的是「这任务打印了什么」，不是逐帧的字节偏移记账。
+   *
+   * 但 `next` 偏移会一并返回：客户端想增量续读时，拿它当 `from` 再调一次即可，
+   * 不必从头拉。`lossy` 也透出去，让客户端知道「有字节被留存策略吃掉了」，
+   * 而不是把一段对不上的输出当成完整的。
+   */
+  follow(sessionId: string, jobId: string, from: number | undefined, signal: AbortSignal): Promise<{
+    jobId: string;
+    text: string;
+    next: number;
+    lossy: boolean;
+    status?: JobView['status'];
+  }>;
+  /**
+   * 终止一个后台任务。
+   *
+   * 内核的 `kill` 是**同步**的，且只有 `requested` / `already-finished` 两种返回；
+   * 「这个任务不存在或该会话看不到它」走 `job/not-found` 远程错误，在这里转成 404。
+   */
+  kill(sessionId: string, jobId: string): JobKillResult;
+}
+//#endregion
 //#region src/host/cloudflared.d.ts
 /**
  * Cloudflare 隧道（cloudflared）管理。
@@ -1669,6 +1916,20 @@ interface RouterOptions {
    * 生产路径由 `index.ts` 传入与交接实际使用**同一个**目录，避免「界面显示 A、落盘在 B」。
    */
   imageFallbackDir?: string;
+  /**
+   * 宿主服务注入面探针报告（见 `host-service-probe.ts`）。
+   *
+   * 可选：不注入则该端点返回 404，测试因此不必每条都补一个字段。
+   * 生产路径由 `index.ts` 在 apply 期间采集后传入 —— 必须是**快照**，
+   * 因为 cordis 的注入属性只在 apply 执行期间可读（见探针文件头注释）。
+   */
+  hostServiceReport?: HostServiceReport;
+  /**
+   * 后台任务（`/chat/sessions/{sessionId}/jobs`）。
+   *
+   * 可选：不注入则这些端点返回 404，测试不必每条都补一个字段。
+   */
+  jobs?: JobAdapter;
 }
 declare class ApiRouter {
   private readonly options;