dsh-deeppilot 0.9.15 → 0.9.17

package/lib/index.d.ts

@@ -1,5 +1,35 @@
 import z from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
+/**
+ * 输入框 `@` 引用候选（PROTOCOL.md「输入框引用扩展」）。
+ *
+ * 数据来源都是 DSH 官方 Remote，经 `typertGateway` 以 owner 身份调用，与 Web 端同一条发现链路：
+ * - 文件：`fileReferences/list {agentId, query}` → `[{path, kind}]`，由主机挂载的提供方
+ *   （如 `dsh-file-reference-local`）在该会话工作目录里排序给出。只给路径，不读文件内容。
+ * - 会话：`sessionReferenceResolver/candidates {agentId, query}` → 带规范 mention
+ *   `@[label](dsh-session:…)` 的候选；手机发送时原样放进提示词，主机负责改写与注入快照。
+ *
+ * 两类服务都是可选挂载（兼容下限 0.2.1-rc.5 没有保证），所以每次按当前服务是否存在判定，
+ * 一类缺席不影响另一类。会话候选不下发工作目录，只给 `sameWorkspace`，避免把本机路径带到手机。
+ */
+interface FileReferenceItem {
+  path: string;
+  kind: 'file' | 'directory';
+}
+interface SessionReferenceItem {
+  sessionId: string;
+  label: string;
+  mention: string;
+  sameWorkspace: boolean;
+}
+interface ReferenceSource<T> {
+  available: boolean;
+  items: T[];
+}
+interface ReferenceCandidates {
+  files: ReferenceSource<FileReferenceItem>;
+  sessions: ReferenceSource<SessionReferenceItem>;
+}
 declare const DEVICE_SCOPES: readonly ['sessions.read', 'prompt.send', 'sessions.manage', 'interactions.respond', 'notifications.register', 'schedule.manage'];
 type DeviceScope = (typeof DEVICE_SCOPES)[number];
 /**
@@ -352,6 +382,8 @@ interface HostSchedulePatch {
 interface WelcomeCapabilities {
   /** 会话命令目录、执行、权限与原生日志导出入口。缺省不支持。 */
   commands?: boolean;
+  /** 输入框 `@` 引用候选：c2s.session.references 可用（文件或会话引用至少一类）。缺省不支持。 */
+  references?: boolean;
   historyPaging: boolean;
   replay: boolean;
   approvals: boolean;
@@ -406,6 +438,26 @@ interface WelcomeCapabilities {
    * see binary-frame.ts). Plugin-level, independent of the host. Absent ⇒ the
    * client must keep requesting base64 text frames. */
   binaryFrames?: boolean;
+  /** Bridge honours `watchSessions` on c2s.auth.prove and c2s.session.watch:
+   * a connection that declared an interest set only receives
+   * s2c.session.event / s2c.session.queue (live and replayed) for sessions it
+   * opened or watches. Plugin-level. Absent ⇒ the client gets every
+   * session's events, as before. */
+  sessionInterest?: boolean;
+  /** Bridge compresses downlink frames over 8 KB as binary format 2
+   * (`[2][deflate-raw(envelope JSON)]`) once the client listed "deflate-raw"
+   * in `acceptEncoding` on c2s.auth.prove. Plugin-level. Absent ⇒ the field is
+   * ignored and every JSON frame stays a text frame. */
+  compressedFrames?: boolean;
+  /** Bridge answers c2s.session.open carrying `sinceSeq` with an incremental
+   * tail (`incremental: true`) holding only rows changed after that seq, or
+   * with a full tail when it cannot prove the delta complete. Plugin-level. */
+  incrementalTail?: boolean;
+  /** Bridge includes `routes` (current LAN endpoints with their certificate
+   * fingerprint, and the public Funnel URL) in s2c.welcome so the client can
+   * prefer the LAN on the same network and fall back to Funnel elsewhere.
+   * Plugin-level. */
+  routeHints?: boolean;
 }
 type SessionStatus = "running" | "idle" | "error" | "unknown";
 /**
@@ -480,8 +532,8 @@ type MessageRole = 'user' | 'assistant' | 'tool' | 'system' | 'error';
 type ToolState = 'running' | 'ok' | 'error';
 /**
  * 文件编辑类工具调用的改动内容（v2 追加式扩展，见 PROTOCOL.md「工具改动对比」）。
- * Bridge 把宿主 `str_replace_editor` 的参数名（old_str/new_str/file_text/insert_line）
- * 归一化成这里的字段，手机端不依赖宿主工具参数命名。`oldText` / `newText` 各自超过
+ * Bridge 把宿主 `edit`（old_string/new_string）、`write`（content）与 `str_replace_editor`
+ * （old_str/new_str/file_text/insert_line）的参数名归一化成这里的字段，手机端不依赖宿主工具参数命名。`oldText` / `newText` 各自超过
  * 16 KiB（UTF-8）时都不发，只带 `truncated: true`。
  */
 interface ToolEditProjection {
@@ -493,6 +545,22 @@ interface ToolEditProjection {
   insertLine?: number;
   truncated?: boolean;
 }
+/**
+ * 工具调用的操作对象（v2 追加式扩展，见 PROTOCOL.md「Message 投影 · tool.target」）。
+ * Bridge 从宿主工具参数里挑出「对什么做」：文件路径、命令、搜索式、网址或其他对象名，
+ * 参数名不外泄。工具结果合并回调用行后 `summary` 会被结果摘要替换，`target` 保留，
+ * 客户端据此在调用完成后仍能显示「读取 A.swift」而不是文件正文片段。
+ * `kind` 是开放词表：客户端遇到未知值按 `text` 处理。
+ */
+interface ToolTargetProjection {
+  kind: 'path' | 'command' | 'pattern' | 'url' | 'text';
+  /** 主值；UTF-8 上限 1 KiB。路径超长时砍开头（保留文件名），其余砍结尾加「…」。 */
+  value: string;
+  /** 范围：搜索所在目录（`pattern` 专用）；UTF-8 上限 1 KiB，规则同路径。 */
+  scope?: string;
+  /** 宿主给的人类可读说明（如 bash 的 description）；UTF-8 上限 256 B。 */
+  label?: string;
+}
 /** Provenance of host-injected context; present only on `role: "system"` rows.
  * Mirrors the durable DSH message source (`dsh-llm` MessageSource): `label`
  * names the producer (plugin name, skill name, instruction paths…), `form` is
@@ -527,6 +595,7 @@ interface MessageProjection {
     state: ToolState;
     summary: string;
     edit?: ToolEditProjection;
+    target?: ToolTargetProjection;
   };
   attachments?: MessageAttachment[];
   /** Present only on system rows: provenance of the injected context.
@@ -588,6 +657,16 @@ interface PendingSnapshotPayload {
   approvals: PendingApprovalPayload[];
   questions: PendingQuestionPayload[];
 }
+/**
+ * 宿主持久化图片引用（ImageAttachmentRef）的原样对象。
+ *
+ * 只要求 `attachmentId`；其余字段（mediaType/bytes/width/height/name/
+ * originalDimensions…）由宿主生成、由宿主读取时自行核对，这里原样保留、不做
+ * 字段裁剪，免得宿主以后新增必填字段时被插件悄悄丢掉。
+ */
+type HostImageRef = Readonly<Record<string, unknown> & {
+  attachmentId: string;
+}>;
 interface CommandsApiLike {
   list(req: RpcRequestLike<{
     sessionId: string;
@@ -612,6 +691,13 @@ interface CommandsApiLike {
     format?: SessionExportFormat;
   }>, signal: AbortSignal): Promise<Response>;
 }
+/** 输入框 `@` 引用候选（文件 + 会话），见 reference-api.ts。 */
+interface ReferencesApiLike {
+  list(req: RpcRequestLike<{
+    sessionId: string;
+    query: string;
+  }>, signal?: AbortSignal): Promise<RpcResponseLike<ReferenceCandidates>>;
+}
 interface RpcOk<T> {
   ok: true;
   value: T;
@@ -685,10 +771,16 @@ interface SessionsApiLike {
   cancel?(req: RpcRequestLike<{
     sessionId: string;
   }>): Promise<RpcResponseLike<Record<string, unknown> | undefined>>;
-  /** Reads one durable image back after the host verifies the session log references its id. */
+  /**
+   * Reads one durable image back. DSH ≤ 0.2.1 reads `attachmentId` and checks the
+   * session log itself; DSH 0.2.2+ reads the full `attachment` reference and no
+   * longer checks the session, so HostBridge sends both and only supplies a
+   * reference it saw projected in that session.
+   */
   attachment?(req: RpcRequestLike<{
     sessionId: string;
     attachmentId: string;
+    attachment?: HostImageRef;
   }>): Promise<RpcResponseLike<{
     attachment: {
       mediaType?: string;
@@ -1077,6 +1169,8 @@ interface ApiProxyLike {
   /** 真实宿主反射声明了助手流帧时才为 true；旧代理缺省关闭。 */
   readonly assistantStreamAvailable?: boolean;
   commands?: CommandsApiLike;
+  /** 主机挂载了文件引用或会话引用服务之一时存在；两者都缺席为 undefined。 */
+  references?: ReferencesApiLike;
   sessions: SessionsApiLike;
   workspace?: WorkspaceApiLike;
   schedule?: ScheduleApiLike;
@@ -1122,6 +1216,14 @@ interface BridgeSink {
    * every push/replay delivery; unknown broadcast types are denied.
    */
   canReceive(scope: DeviceScope): boolean;
+  /**
+   * Interest filter (capability `sessionInterest`): whether this sink wants a
+   * frame it is already permitted to receive. Connections that declared an
+   * interest set drop other sessions' events here. Absent ⇒ wants everything.
+   * The bridge consults it when sizing a replay window; sinks apply it again
+   * on every push.
+   */
+  accepts?(type: string, payload: unknown): boolean;
 }
 /**
  * Offline push fan-out (F-9 离线推送). The bridge forwards every
@@ -1219,6 +1321,13 @@ export declare class HostBridge {
   private readonly log?;
   readonly id: number;
   private summaries;
+  /**
+   * 列表推送节流（连接传输第二批 P5）。每个会话最近一次推出去的摘要指纹，
+   * 用来丢掉内容完全相同的重复推送；只改了 `stats` 的变化按 SUMMARY_STATS_THROTTLE_MS
+   * 合并，状态、标题、任务清单、待处理标记、活动描述的变化照旧立即推。
+   */
+  private readonly summaryPushed;
+  private readonly summaryStatsTimers;
   private activeTools;
   private approvals;
   private questions;
@@ -1242,6 +1351,8 @@ export declare class HostBridge {
   private abort;
   private started;
   private disposed;
+  /** attachmentId → 宿主完整图片引用，供 attachmentData 补全 DSH 0.2.2+ 的读图参数。 */
+  private readonly imageRefs;
   readonly promptDeliveries: DispatchJournal<{
     sessionId: string;
     content: unknown;
@@ -1307,6 +1418,12 @@ export declare class HostBridge {
    * reader without interactions.respond never gets the missed approval
    * frames back (R1/P2).
    */
+  /**
+   * 按序补发游标之后的帧。先按权限与关注集合筛出该 sink 真正会收到的帧，
+   * 估算字节数超过 REPLAY_RESYNC_BYTES 时改发 `s2c.resync`：补发是同步一次性
+   * 写出的，经 Funnel 时插件这侧看不到积压，大补发会把之后所有请求响应堵在
+   * 链路上（实测 450 帧堵 37 秒）。重新同步让客户端只拉列表和正在看的会话。
+   */
   resumeFrom(cursor: number, target?: BridgeSink): boolean;
   refreshLiveActivities(): void;
   private record;
@@ -1345,6 +1462,8 @@ export declare class HostBridge {
   private applyProjection;
   private bumpPendingFlags;
   private pushSummary;
+  private noteSummaryPushed;
+  private forgetSummaryPush;
   listSessions(): SessionSummary[];
   /**
    * Archived rows from the last sessions.list, newest first. Served only on
@@ -1361,7 +1480,7 @@ export declare class HostBridge {
   /** Resolve only the exact invocation in this session; never guess from the latest tool. */
   private loadApprovalArguments;
   /** Tail history for an opened session; pushes s2c.session.tail to the sink. */
-  openSession(sink: BridgeSink, sessionId: string, tailCount: number): Promise<boolean>;
+  openSession(sink: BridgeSink, sessionId: string, tailCount: number, sinceSeq?: number): Promise<boolean>;
   /**
    * Pull one session's projection baseline and fold every key
    * through applyProjection — unknown keys are ignored there, `null` means the
@@ -1374,12 +1493,28 @@ export declare class HostBridge {
     messages: MessageProjection[];
     hasMore: boolean;
   } | null>;
-  /** Result of one attachment read-back for the phone. */
+  /**
+   * Result of one attachment read-back for the phone.
+   *
+   * 宿主读图参数有两代：DSH ≤ 0.2.1 收 `{sessionId, attachmentId}` 并自己在会话日志里
+   * 找引用；DSH 0.2.2 起改收 `{sessionId, attachment: 完整引用}`，且不再核对会话。
+   * 控制器是直接注入的实例、不经参数 schema 校验，所以两代字段一起传：旧宿主读前者，
+   * 新宿主读后者。完整引用来自 imageRefs（本会话投影过的图片）；找不到时不带
+   * `attachment`，旧宿主照常自查，新宿主读不到即回 null（E_NOT_FOUND）——手机因此
+   * 读不到不属于该会话的图片。
+   */
   attachmentData(sessionId: string, attachmentId: string): Promise<{
     mediaType?: string;
     data: string;
   } | null>;
+  /** 图片引用回查用的原始历史页：只取事件，不投影、不推给手机。 */
+  private readHistoryEvents;
   commandOperation(operation: 'list' | 'execute' | 'permissions' | 'feedback', payload: Record<string, unknown>): Promise<SessionManagementResult<unknown>>;
+  /**
+   * 输入框 `@` 引用候选。两类候选的单类失败已在 reference-api 内吸收为空列表，
+   * 这里只处理「两类都不可用」与代理层意外异常。
+   */
+  referenceCandidates(sessionId: string, query: string, signal?: AbortSignal): Promise<SessionManagementResult<ReferenceCandidates>>;
   exportSession(sessionId: string, signal: AbortSignal, format?: SessionExportFormat): Promise<Response>;
   /** 由会话目录决定技能可见性；不读取正文，也不把本机路径发给移动端。 */
   sessionSkills(sessionId: string): Promise<SessionManagementResult<{