dsh-deeppilot 0.9.1 → 0.9.3

package/lib/index.d.ts

@@ -1,39 +1,238 @@
-import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-//#region src/prompt-delivery.d.ts
-type DeliveryStatus = 'accepted' | 'rejected' | 'unknown' | 'notFound' | 'expired';
-interface DeliveryReceipt {
-  clientSendId: string;
-  status: DeliveryStatus;
-  userSeq?: number;
-  code?: string;
+import { Context } from "@deepseek-ai/cordis";
+//#region src/wire-errors.d.ts
+/**
+ * 错误词表（error vocabulary）的唯一属主。
+ *
+ * 一条失败信息在系统里要过三种词汇：Host 控制器返回的错误码（`session-not-found`、
+ * `schedule_conflict`……）、Bridge 结果里的状态、以及 wire 上的 `E_*` 码。
+ * 此前这三层各有映射函数（host-bridge 里 5 个、connection-policy 里 2 个、
+ * connection.ts 的 switch 里 5 处内联三元链），一处漂移就会让客户端对
+ * 「该不该重试」的判断失真。
+ *
+ * 本 module 只做一次翻译：每个域一张「Host code -> wire code」表，
+ * Bridge 的结果直接携带 wire 码。`E_BUSY` 与 `E_PROTOCOL` 决定客户端是否
+ * 重试，因此这张表是 wire 行为的一部分，逐码都有测试把守。
+ *
+ * 规范见 PROTOCOL.md 错误码表（`E_PROTOCOL` = 未知类型或非法 payload，
+ * `E_FORBIDDEN` = 权限不足，`E_UNSUPPORTED` = 能力缺失）。
+ */
+/** wire 错误码及其规范描述；PROTOCOL.md 错误码表的 TS 镜像。 */
+declare const ERROR_CODES: {
+  readonly E_AUTH: 'device proof missing or invalid';
+  readonly E_FORBIDDEN: 'device scope does not allow this operation';
+  readonly E_PROTOCOL: 'unknown type or malformed payload';
+  readonly E_NOT_FOUND: 'session or request not found';
+  readonly E_BUSY: 'session is busy';
+  readonly E_UNSUPPORTED: 'protocol version or capability unsupported';
+  readonly E_INTERNAL: 'internal error';
+};
+type WireErrorCode = keyof typeof ERROR_CODES;
+//#endregion
+//#region src/dispatch-journal.d.ts
+/** 落盘条目：两个通用字段 + codec 私有字段。 */
+interface JournalEntry {
+  fingerprint: string;
+  createdAt: number;
+  [field: string]: unknown;
+}
+/** operation 的结果：成功带值，失败带 wire 错误码。 */
+type OperationResult<T = unknown> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  code: WireErrorCode;
+  message?: string;
+};
+/**
+ * 一切「不看条目就能定」的结果类别。codec 用一个方法把它们翻译成自己的方言，
+ * 而不是让核心知道任何一方的形状。
+ */
+type DispatchOutcome =
+/** 命中既有条目（重放）。 */
+{
+  kind: 'replay';
+  entry: JournalEntry;
+} |
+/** 同一 id 搭不同内容。 */
+{
+  kind: 'mismatch';
+} |
+/** 构造期解析失败：journal 已永久降级，本次进程不再投递。 */
+{
+  kind: 'unavailable';
+} |
+/** id 的纪元前缀超出保留窗口。 */
+{
+  kind: 'expired';
+} |
+/** 条目数已达容量上限。 */
+{
+  kind: 'full';
+} |
+/** 刚跑完的那一次：operation 的结果原样带出（不标 replayed）。 */
+{
+  kind: 'ran';
+  entry: JournalEntry;
+  result: OperationResult;
+} |
+/** operation 抛错：条目保持 unknown，且不得自动重试。 */
+{
+  kind: 'crashed';
+} |
+/**
+ * 预留条目时落盘失败——上游**没有**被调用，但无从判断 rename 是否已经
+ * 生效（save() 可能在 rename 之后才抛），因此条目留在内存里按 unknown 处理。
+ */
+{
+  kind: 'reserve-failed';
+} |
+/** id 形状不合法（仅 mutation 变体开启这道守卫）。 */
+{
+  kind: 'invalid-id';
+};
+interface DispatchCodec<TRequest = unknown, TResult = unknown> {
+  /** 实例身份：opener 单例键的一部分（含 persistValues 等变体差异）。 */
+  readonly identity: string;
+  /** 请求指纹。prompt 覆盖 [sessionId, content]；mutation 只覆盖 content。 */
+  fingerprint(request: TRequest): string;
+  /** 预留条目时写入的 codec 字段（fingerprint/createdAt 由核心补）。 */
+  reserve(request: TRequest, id: string): Record<string, unknown>;
+  /** operation 成功后就地更新条目。 */
+  accepted(entry: JournalEntry, id: string, value: unknown): void;
+  /** operation 失败后就地更新条目。 */
+  rejected(entry: JournalEntry, id: string, code: WireErrorCode): void;
+  /** 把结果类别翻译成调用方言。 */
+  resultOf(outcome: DispatchOutcome, id: string): TResult;
+  /** id 非法时是否先拒掉（mutation 是；prompt 由 wire 层保证，故否）。 */
+  readonly requiresValidId?: boolean;
+  /** lookup 的匹配规则；缺省表示该实例不提供 lookup。 */
+  matches?(entry: JournalEntry, request: unknown): boolean;
+  /** lookup 未命中时回什么（prompt 要区分 notFound / expired）。 */
+  miss?(id: string, expired: boolean): TResult;
+  /** 落盘容器 → 内存条目表；任何不合法都抛错（核心转成 healthy=false）。 */
+  parse(raw: unknown): Record<string, JournalEntry>;
+  /** 内存条目表 → 落盘容器。 */
+  serialize(entries: Record<string, JournalEntry>): unknown;
+}
+interface DispatchJournalOptions<TRequest = unknown, TResult = unknown> {
+  codec: DispatchCodec<TRequest, TResult>;
+  path?: string;
+  /** 落盘体积上限：prompt 8MB、mutation 4MB（由条目实际大小决定，不统一）。 */
+  maxFileBytes?: number;
+  capacity?: number;
+  retentionMs?: number;
+  /**
+   * 并发重复是否搭同在途那次。prompt 是（重复方拿到同一个最终回执）；
+   * mutation 否（重复方立刻拿到 unknown → E_INTERNAL）。两者都由对等快照钉住。
+   */
+  joinInFlight?: boolean;
+  /**
+   * 落盘失败的诊断输出。由调用方注入它已有的 logger；缺省即静默。
+   * 只打阶段与 errno，绝不打条目内容或消息体（plugin 的日志禁令）。
+   */
+  log?: (message: string) => void;
+  /**
+   * 目录 fsync 里「对 fd 调用 fsync」这一步的覆盖点，缺省即 `fsyncSync`。
+   *
+   * 存在的唯一理由是可测：Linux CI 上复现不出 Windows 的 EPERM。注入点刻意
+   * 停在 fd 这一层而不是替换整个目录 fsync——容忍 EPERM 的判断必须留在真实
+   * 路径里被测到，换掉整函数就等于把待测逻辑一起换掉了。
+   */
+  fsyncFileDescriptor?: (fd: number) => void;
 }
 /** Durable at-most-once dispatch. Unknown outcomes are never automatically retried. */
-declare class PromptDeliveryJournal {
-  private readonly path?;
-  private readonly capacity;
+declare class DispatchJournal<TRequest = unknown, TResult = unknown> {
+  private readonly options;
   private entries;
   private inFlight;
+  /** 只由构造期的解析失败置位，见下方 catch；运行期落盘失败不碰它。 */
   private healthy;
-  constructor(path?: string | undefined, capacity?: number);
+  private readonly maxFileBytes;
+  private readonly capacity;
+  private readonly retentionMs;
+  private readonly joinInFlight;
+  constructor(options: DispatchJournalOptions<TRequest, TResult>);
   private key;
+  /** id 的纪元前缀是否还在保留窗口内（未来 5 分钟以上同样算非法）。 */
   private expired;
   private save;
-  lookup(deviceId: string, sessionId: string, id: string): DeliveryReceipt;
-  dispatch(deviceId: string, sessionId: string, id: string, content: unknown, operation: () => Promise<{
-    ok: true;
-    value: number;
-  } | {
-    ok: false;
-    kind: string;
-  }>): Promise<DeliveryReceipt>;
+  /**
+   * 落盘一次，失败只报不降级。
+   *
+   * 与 `healthy` 的分工：`healthy` 只由构造期的解析失败置位，运行期的磁盘错误
+   * 不再拉黑整个进程——此前一次 save() 失败就让本进程余下的所有投递永久返回
+   * unknown，直到 DSH 重启（issue #20 / #26）。现在只影响当次投递，下一次
+   * dispatch 会重新尝试。
+   */
+  private persist;
+  /** 查询既有回执；`request` 交给 codec 的 matches 判定（缺省即不提供 lookup）。 */
+  lookup(deviceId: string, id: string, request?: unknown): TResult | undefined;
+  /**
+   * 幂等投递。未知结果绝不自动重试：条目保持 unknown，重放时由 codec 决定
+   * 调用方看到什么。
+   */
+  dispatch(deviceId: string, id: string, request: TRequest, operation: () => Promise<OperationResult>): Promise<TResult>;
+  /** 等所有在途投递结束；供进程收尾。 */
+  settled(): Promise<void>;
+}
+/** prompt 投递的回执：手机侧按 clientSendId 对账。 */
+type DeliveryStatus = 'accepted' | 'rejected' | 'unknown' | 'notFound' | 'expired';
+interface DeliveryReceipt {
+  clientSendId: string;
+  status: DeliveryStatus;
+  userSeq?: number;
+  code?: string;
 }
+/** mutation 的结果：replayed 让调用方知道这是重放而非新执行。 */
+type MutationErrorCode = WireErrorCode;
+type MutationDispatchResult<T> = {
+  ok: true;
+  value?: T;
+  replayed?: boolean;
+} | {
+  ok: false;
+  code: MutationErrorCode;
+  message?: string;
+  replayed?: boolean;
+};
 //#endregion
 //#region src/device-auth.d.ts
 declare const DEVICE_SCOPES: readonly ['sessions.read', 'prompt.send', 'sessions.manage', 'interactions.respond', 'notifications.register', 'schedule.manage'];
 type DeviceScope = (typeof DEVICE_SCOPES)[number];
 //#endregion
 //#region src/protocol.d.ts
+interface WelcomeCapabilities {
+  historyPaging: boolean;
+  replay: boolean;
+  approvals: boolean;
+  questions: boolean;
+  /** Client can request the complete currently-pending approval/question set. */
+  pendingSnapshot?: boolean;
+  promptDelivery?: boolean;
+  /** Bridge emits s2c.notify for all four notification categories. */
+  notifyAllCategories?: boolean;
+  models: boolean;
+  sessionManagement: boolean;
+  /** Bridge can fork a session at an exact event boundary. */
+  sessionFork?: boolean;
+  /** Bridge can list archived sessions and restore them
+   * (c2s.sessions.archived / c2s.session.unarchive). Absent on hosts whose
+   * workspace controller predates unarchiveSession. */
+  sessionRestore?: boolean;
+  projectSelection: boolean;
+  /** Host exposes the optional DSH Schedule service. */
+  schedules?: boolean;
+  /** Bridge has APNs configured; clients may send c2s.push.register. */
+  push?: boolean;
+  widgetPush?: boolean;
+  liveActivityPush?: boolean;
+  /** Bridge accepts c2s.device.revoke, letting a client unbind itself before
+   * deleting its local credentials. Absent on older bridges; older clients
+   * ignore the extra field. */
+  deviceRevoke?: boolean;
+}
 type SessionStatus = "running" | "idle" | "error" | "unknown";
 /**
  * Cumulative model/token statistics for one session, mirrored from the
@@ -435,12 +634,17 @@ interface HostSessionModels {
     message: string;
   }>;
 }
+/**
+ * Bridge 方法的结果。失败直接携带 wire 错误码（error vocabulary 见
+ * wire-errors.ts）：调用方（wire-registry 的行）原样透给手机，不再经过
+ * kind 中间层翻译。
+ */
 type ModelBridgeResult<T> = {
   ok: true;
   value: T;
 } | {
   ok: false;
-  kind: 'unsupported' | 'not-found' | 'busy' | 'unavailable' | 'internal';
+  code: WireErrorCode;
   message: string;
 };
 type SessionManagementResult<T> = {
@@ -448,7 +652,7 @@ type SessionManagementResult<T> = {
   value: T;
 } | {
   ok: false;
-  kind: 'unsupported' | 'not-found' | 'busy' | 'invalid' | 'internal';
+  code: WireErrorCode;
   message: string;
 };
 interface PromptArgs {
@@ -597,62 +801,30 @@ interface PromptDocument {
   truncated?: boolean;
 }
 //#endregion
-//#region src/mutation-journal.d.ts
-type MutationErrorCode = 'E_PROTOCOL' | 'E_NOT_FOUND' | 'E_BUSY' | 'E_UNSUPPORTED' | 'E_INTERNAL';
-type MutationOperationResult<T> = {
-  ok: true;
-  value: T;
-} | {
-  ok: false;
-  code: MutationErrorCode;
-  message?: string;
-};
-type MutationDispatchResult<T> = {
-  ok: true;
-  value?: T;
-  replayed?: boolean;
-} | {
-  ok: false;
-  code: MutationErrorCode;
-  message?: string;
-  replayed?: boolean;
-};
+//#region src/host-bridge.d.ts
 /**
- * Small durable at-most-once journal for non-prompt mutations.
+ * 失败结果直接携带 wire 错误码（error vocabulary 见 wire-errors.ts）。
  *
- * Only a hash of the request content is persisted. The successful value is
- * kept in memory for the current process so a concurrent retry can receive the
- * same response; after a restart a replay is acknowledged and the client
- * refetches the authoritative resource. This avoids duplicating reminder
- * prompts or conversation data in a second journal.
+ * 迁移前这里有 kind 中间层（'not-found' | 'busy' | 'conflict' | 'invalid'…），
+ * 由 5 个映射函数在「Host code ↔ kind ↔ E_*」之间来回翻译，其中
+ * E_BUSY→conflict→E_BUSY 的往返已证明有损。现在每个域查一次表，调用方拿到的
+ * 就是手机上会看到的错误码。
  */
-declare class MutationJournal {
-  private readonly path?;
-  private readonly persistValues;
-  private readonly entries;
-  private readonly inFlight;
-  private healthy;
-  constructor(path?: string | undefined, persistValues?: boolean);
-  private key;
-  private expired;
-  private save;
-  dispatch<T>(deviceId: string, id: string, content: unknown, operation: () => Promise<MutationOperationResult<T>>): Promise<MutationDispatchResult<T>>;
-}
-//#endregion
-//#region src/host-bridge.d.ts
 type ScheduleBridgeResult<T> = {
   ok: true;
   value: T;
   replayed?: boolean;
 } | {
   ok: false;
-  kind: 'unsupported' | 'not-found' | 'invalid' | 'conflict' | 'busy' | 'internal';
+  code: WireErrorCode;
   message: string;
   replayed?: boolean;
 };
 declare class HostBridge {
   private readonly apiProxy;
   private readonly historyBufferMax;
+  /** 三个 journal 的落盘失败诊断输出；缺省即静默。不打任何消息体。 */
+  private readonly log?;
   readonly id: number;
   private summaries;
   private activeTools;
@@ -670,10 +842,15 @@ declare class HostBridge {
   private abort;
   private started;
   private disposed;
-  readonly promptDeliveries: PromptDeliveryJournal;
-  readonly scheduleMutations: MutationJournal;
-  readonly forkMutations: MutationJournal;
-  constructor(apiProxy: ApiProxyLike, historyBufferMax?: number, deliveryJournalPath?: string, scheduleJournalPath?: string, forkJournalPath?: string);
+  readonly promptDeliveries: DispatchJournal<{
+    sessionId: string;
+    content: unknown;
+  }, DeliveryReceipt>;
+  readonly scheduleMutations: DispatchJournal<unknown, MutationDispatchResult<unknown>>;
+  readonly forkMutations: DispatchJournal<unknown, MutationDispatchResult<unknown>>;
+  constructor(apiProxy: ApiProxyLike, historyBufferMax?: number, deliveryJournalPath?: string, scheduleJournalPath?: string, forkJournalPath?: string,
+  /** 三个 journal 的落盘失败诊断输出；缺省即静默。不打任何消息体。 */
+  log?: ((message: string) => void) | undefined);
   private pushOutlet;
   private widgetFingerprint;
   /**
@@ -681,25 +858,12 @@ declare class HostBridge {
    * capability and notify-worthy events are mirrored to APNs.
    */
   setPushOutlet(outlet: PushOutlet | undefined): void;
-  get capabilities(): {
-    historyPaging: boolean;
-    replay: boolean;
-    approvals: boolean;
-    questions: boolean;
-    pendingSnapshot: boolean;
-    promptDelivery: boolean;
-    notifyAllCategories: boolean;
-    models: boolean;
-    sessionManagement: boolean;
-    sessionFork: boolean;
-    sessionRestore: boolean;
-    projectSelection: boolean;
-    schedules: boolean;
-    push: boolean;
-    widgetPush: boolean;
-    liveActivityPush: boolean;
-    deviceRevoke: boolean;
-  };
+  /**
+   * welcome 能力位。委托 host-capabilities.ts 的探测表：此前同一条事实在这里
+   * 和各方法体内各存一份，已经漂移过两次（models 位过严、schedules 位与
+   * schedule 方法的探测不同源）。
+   */
+  get capabilities(): WelcomeCapabilities;
   diagnostic(message: string): void;
   currentCursor(): number;
   addSink(sink: BridgeSink): void;