dsh-remote-bridge 2.4.2 → 2.5.0

package/lib/index.d.ts

@@ -78,7 +78,9 @@ declare class WorkspaceDatabase {
   readonly dataDir: string;
   readonly trashDir: string;
   private readonly db;
+  private closed;
   constructor(dataDir: string);
+  /** 关闭数据库。**幂等** —— 重复调用不抛错。 */
   close(): void;
   /**
    * 导出 `roots` 的建表语句（只读，诊断与迁移测试用）。
@@ -218,6 +220,12 @@ interface ConfigurableProvider {
   settingsPath: string[];
   active: boolean;
   declared?: boolean;
+  defaultBaseURL?: string;
+  baseURLEnv?: string[];
+  nativeAuth?: {
+    env?: string[];
+    oauth?: boolean;
+  };
 }
 interface SettingsApiProxy extends DshApiProxy {
   settings: {
@@ -326,6 +334,14 @@ interface ProviderView {
   configurable: boolean;
   configured: boolean;
   removable: boolean;
+  defaultBaseURL?: string;
+  baseURLEnv?: string[];
+  nativeAuth?: {
+    env?: string[];
+    oauth?: boolean;
+  };
+  /** 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。 */
+  settingsNs?: string;
   credential: {
     ref: string;
     configured: boolean;
@@ -341,7 +357,8 @@ interface ProviderPatch {
   apiKey?: string | null;
   thinking?: string | null;
   reasoningEffort?: string | null;
-  models?: ProviderModelView[];
+  /** `null` 恢复适配器默认模型目录（unset），`[]` 写入自定义空目录。 */
+  models?: ProviderModelView[] | null;
   expectedRevision?: number;
 }
 interface CustomProviderCreate {
@@ -671,6 +688,57 @@ interface AgentPresetsLike {
 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 {
@@ -687,6 +755,14 @@ interface LlmLike {
     settingsNs: string;
     settingsPath: readonly string[];
     declared?: boolean;
+    defaultBaseURL?: string;
+    /** Environment variables that may override the default base URL, in priority order. */
+    baseURLEnv?: readonly string[];
+    /** Native authentication the adapter can fall back to when no key is stored. */
+    nativeAuth?: {
+      env?: readonly string[];
+      oauth?: boolean;
+    };
     error?: string;
   }[];
   discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
@@ -710,7 +786,31 @@ interface Dsh02HostServices {
   settingsController: SettingsControllerLike;
   credentialsController: CredentialsControllerLike;
   agentPresets: AgentPresetsLike;
-  permissionPresets: PermissionPresetsLike;
+  /**
+   * 权限档位目录（`ctx.permissionPresets`）——**可选**。
+   *
+   * 0.2.1 的 web profile 上有；0.2.0-rc.2 上没有。inject 是硬依赖，
+   * 所以它不能进 inject，只能声明成可选，由 `optionalService` 运行时读；
+   * 读不到时权限档位走 `FALLBACK_PERMISSION_CATALOG` + BFF。
+   */
+  permissionPresets?: PermissionPresetsLike;
+  /**
+   * 后台任务控制器（`ctx.jobController`，`@deepseek-ai/dsh-api-job-controller`）。
+   *
+   * 为什么要它：远程场景下「任务跑飞了停不掉」是真焦虑 —— 人不在电脑前，
+   * 一个卡住的 bash 任务只能干等。手机端需要能看到清单并终止它。
+   *
+   * 与 `sessionController` 不同，这个是 `TypertRemoteService`（不是 `@Remote`
+   * 控制器集合），但结构类型消费方式完全一样：只声明用到的成员，缺了就明确报错。
+   */
+  /**
+   * 后台任务控制器（`ctx.jobController`）——**可选**。
+   *
+   * 只有 DSH 0.2.1 的 web profile 挂了这个服务；0.2.0-rc.2 上没有，
+   * 而 inject 是硬依赖（缺一个整个插件不激活），所以它**不能**出现在 inject 里，
+   * 只能在这里声明成可选，由 `optionalService` 运行时读。
+   */
+  jobController?: JobControllerLike;
   llm: LlmLike;
   /**
    * 内核附件存储（`ctx.attachments`）；会话历史里的图片要经它取字节。
@@ -721,14 +821,23 @@ interface Dsh02HostServices {
    * `cannot get property "attachments" without inject` —— 请求链路本身没问题，
    * 挂在服务端、而且只在真的去取图时才炸，所以很难在本地测出来。
    */
-  attachments: AttachmentStoreLike;
   /**
-   * Kernel file-upload service (`ctx.fileUploads`).
+   * 内核附件存储（`ctx.attachments`）——**可选**。
+   *
+   * 0.2.0-rc.2 的 web profile 上没有这个服务（诊断日志实测 MISSING），
+   * 而 inject 是硬依赖，所以它只能声明成可选，由 `optionalService` 运行时读；
+   * 读不到时附件读取走内核 `sessionController.attachment()`。
+   */
+  attachments?: AttachmentStoreLike;
+  /**
+   * Kernel file-upload service (`ctx.fileUploads`)——**可选**。
    *
    * 为什么用它而不是内核那条 `/api/session/uploadFileBinary` HTTP 路由：那条路由
    * 只绑 loopback（手机根本到不了），而这个 cordis 服务就在同一个进程里，插件可直接调。
+   *
+   * 可选的原因同 [attachments]：0.2.0-rc.2 的 web profile 上没有它。
    */
-  fileUploads: FileUploadsLike;
+  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
@@ -1533,6 +1642,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）管理。
@@ -1725,6 +1964,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;