dsh-remote-bridge 0.0.0-stage → 2.2.0

package/lib/index.d.ts

@@ -0,0 +1,1261 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/shared/contracts.d.ts
+declare const DEVICE_SCOPES: readonly ["chat.read", "chat.write", "files.read", "files.write", "files.delete", "settings.read", "settings.write"];
+type DeviceScope = (typeof DEVICE_SCOPES)[number];
+interface RootView {
+  id: string;
+  label: string;
+  createdAt: number;
+}
+interface DeviceView {
+  id: string;
+  name: string;
+  scopes: DeviceScope[];
+  rootIds: string[];
+  createdAt: number;
+  lastSeenAt?: number;
+  revokedAt?: number;
+}
+interface FileEntryView {
+  name: string;
+  path: string;
+  kind: 'file' | 'directory' | 'symlink' | 'other';
+  size: number;
+  modifiedAt: number;
+  writable: boolean;
+}
+interface WorkspaceEvent {
+  id: string;
+  type: string;
+  time: number;
+  data: Record<string, unknown>;
+}
+interface AdminPrincipal {
+  kind: 'admin';
+  id: 'loopback-admin';
+  scopes: ReadonlySet<DeviceScope>;
+  rootIds: 'all';
+}
+interface DevicePrincipal {
+  kind: 'device';
+  id: string;
+  name: string;
+  scopes: ReadonlySet<DeviceScope>;
+  rootIds: ReadonlySet<string>;
+}
+type Principal = AdminPrincipal | DevicePrincipal;
+//#endregion
+//#region src/host/database.d.ts
+interface StoredRoot extends RootView {
+  realPath: string;
+}
+interface AuthenticatedDevice extends DeviceView {
+  tokenHash: string;
+}
+interface TrashRecord {
+  id: string;
+  rootId: string;
+  relativePath: string;
+  payloadPath: string;
+  kind: string;
+  size: number;
+  digest: string;
+  createdAt: number;
+  status: string;
+}
+declare class WorkspaceDatabase {
+  readonly dataDir: string;
+  readonly trashDir: string;
+  private readonly db;
+  constructor(dataDir: string);
+  close(): void;
+  getSetting(key: string): string | undefined;
+  setSetting(key: string, value: string): void;
+  addRoot(inputPath: string, label?: string): Promise<StoredRoot>;
+  listRoots(): StoredRoot[];
+  getRoot(id: string): StoredRoot | undefined;
+  removeRoot(id: string): void;
+  createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number): {
+    code: string;
+    expiresAt: number;
+  };
+  exchangePairing(code: string, deviceName: string): {
+    token: string;
+    device: DeviceView;
+  };
+  authenticate(token: string): AuthenticatedDevice | undefined;
+  getActiveDevice(id: string): AuthenticatedDevice | undefined;
+  private hydrateDevice;
+  listDevices(): DeviceView[];
+  isDeviceActive(id: string): boolean;
+  updateDevice(id: string, scopes: DeviceScope[], rootIds: string[]): DeviceView;
+  revokeDevice(id: string): void;
+  insertTrash(record: TrashRecord): void;
+  updateTrashStatus(id: string, status: string): void;
+  getTrash(id: string): TrashRecord | undefined;
+  listTrash(rootIds?: ReadonlySet<string>): TrashRecord[];
+  deleteTrashRecord(id: string): void;
+  audit(actorType: string, actorId: string, action: string, rootId?: string, relativePath?: string, details?: Record<string, unknown>, requestId?: string): void;
+  listAudit(limit?: number): Record<string, unknown>[];
+  readIdempotent(deviceId: string, key: string): {
+    status: number;
+    body: unknown;
+  } | undefined;
+  saveIdempotent(deviceId: string, key: string, status: number, body: unknown): void;
+  private migrate;
+}
+//#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;
+    };
+  };
+}
+/**
+ * 一条 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(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        mode: 'queue' | 'steer';
+        content: PromptContentPart[];
+        clientTimeZone?: string;
+      };
+    }): 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，多一次编解码纯属浪费。
+     */
+    readAttachment(request: {
+      rpcId: string;
+      payload: {
+        attachmentId: string;
+      };
+    }): Promise<RpcResponse<{
+      bytes: Uint8Array;
+      mediaType: string;
+    }>>;
+    cancel(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+      };
+    }): Promise<RpcResponse<{
+      accepted: true;
+    }>>;
+    rename(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        title: string;
+      };
+    }): Promise<RpcResponse<{
+      title: string;
+      seq: number;
+    }>>;
+    fork(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        atSeq?: number;
+      };
+    }): 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;
+    }>>;
+  };
+  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;
+    }>>;
+  };
+  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 {
+  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;
+}
+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 DshWorkspaceSummary {
+  workspaceId: string;
+  path: string;
+  title: string;
+  sessionIds: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+interface DshAgentPresetSummary {
+  id: string;
+  trust: 'system' | 'user';
+  isDefault: boolean;
+  name?: string;
+  description?: string;
+  broken?: string;
+}
+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 PendingApprovalView {
+  id: string;
+  sessionId: string;
+  toolName: string;
+  reason?: string;
+  detail?: string;
+  risk: 'standard' | 'full-access';
+  requestedAt: number;
+}
+interface ChatWorkspaceView {
+  id: string;
+  title: string;
+  rootId: string;
+  path: string;
+  createdAt: string;
+  updatedAt: 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<{
+    id: string;
+    agentPreset?: string;
+  }>;
+  createSession(principal: Principal, rootId: string, relativePath: string, options: {
+    sessionId?: string;
+    agentPreset?: string;
+  }): Promise<{
+    id: string;
+    agentPreset?: string;
+  }>;
+  history(principal: Principal, sessionId: string, options: {
+    beforeSeq?: number;
+    maxMessages?: number;
+  }): Promise<{
+    events: unknown[];
+    hasMore: boolean;
+    projections?: unknown;
+  }>;
+  prompt(principal: Principal, sessionId: string, parts: PromptContentPart[], mode: 'queue' | 'steer', clientTimeZone?: string): Promise<{
+    accepted: true;
+    command?: unknown;
+  }>;
+  /**
+   * 上传一个附件，返回 prompt 可以引用的凭证。
+   *
+   * 为什么需要这一步而不是让客户端直接把字节塞进消息：内核对**文件**类型要求的是
+   * `receiptId`（由上传换取），只有**图片**才允许内联 base64。
+   */
+  uploadAttachment(principal: Principal, sessionId: string, data: string, name?: string): Promise<{
+    receiptId: string;
+    name: string | null;
+  }>;
+  /**
+   * 取回会话历史里某个图片附件的字节。
+   *
+   * 这里不做会话归属校验：附件 id 是内容哈希，拿到 id 就等于拿到内容，
+   * 而且调用方必须已经通过 `files.read` 鉴权并主动持有该 id（它只出现在其有权读取的
+   * 会话事件里）。多一层会话校验并不能提升安全性，却会让「在别的会话里引用同一张图」
+   * 这种正常情况莫名失败。
+   */
+  readAttachment(principal: Principal, attachmentId: string): Promise<{
+    bytes: Uint8Array;
+    mediaType: string;
+  }>;
+  cancel(principal: Principal, sessionId: string): Promise<void>;
+  renameSession(principal: Principal, sessionId: string, title: string): Promise<{
+    title: string;
+    seq: number;
+  }>;
+  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>;
+  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;
+  /**
+   * Resolve the Agent backing a session for command work.
+   *
+   * 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).
+   */
+  private commandAgent;
+  private requireSession;
+  private requireWorkspace;
+  private visibleWorkspaces;
+  private requireAuthorizedRoot;
+  private authorizedRoots;
+  private sessionRootId;
+}
+//#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;
+}
+interface SettingsApiProxy extends DshApiProxy {
+  settings: {
+    describe(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }): Promise<RpcResponse<{
+      writable: boolean;
+      hasDocument: boolean;
+      namespaces: SettingsNamespaceView[];
+    }>>;
+    mutate(request: {
+      rpcId: string;
+      payload: {
+        ns: string;
+        ops: Array<{
+          op: 'set';
+          path: string[];
+          value: unknown;
+        } | {
+          op: 'unset';
+          path: string[];
+        }>;
+        expectedRevision?: number;
+      };
+    }): Promise<RpcResponse<SettingsNamespaceView>>;
+  };
+  credentials: {
+    describe(request: {
+      rpcId: string;
+      payload: {
+        refs: string[];
+      };
+    }): Promise<RpcResponse<{
+      credentials: Record<string, {
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+      }>;
+    }>>;
+    set(request: {
+      rpcId: string;
+      payload: {
+        ref: string;
+        value: string;
+      };
+    }): Promise<RpcResponse<Record<string, never>>>;
+    unset(request: {
+      rpcId: string;
+      payload: {
+        ref: string;
+      };
+    }): Promise<RpcResponse<Record<string, never>>>;
+  };
+  llm: {
+    providers(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }): Promise<RpcResponse<{
+      providers: ConfigurableProvider[];
+    }>>;
+    models(request: {
+      rpcId: string;
+      payload: Record<string, never>;
+    }): Promise<RpcResponse<{
+      groups: ModelProviderGroupView[];
+      failures: {
+        provider: string;
+        message: string;
+      }[];
+    }>>;
+    discoverModels(request: {
+      rpcId: string;
+      payload: {
+        settingsNs: string;
+        provider?: string;
+        baseURL?: string;
+        api?: string;
+        apiKey?: string;
+      };
+    }): Promise<RpcResponse<{
+      models: ProviderModelView[];
+    }>>;
+  };
+}
+interface ProviderModelView {
+  id: string;
+  name?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+}
+interface ProviderConfigView {
+  baseURL?: string;
+  api?: string;
+  displayName?: string;
+  thinking?: string;
+  reasoningEffort?: string;
+  models: ProviderModelView[];
+  modelsInherited?: boolean;
+}
+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 ProviderPatch {
+  displayName?: string | null;
+  baseURL?: string | null;
+  api?: string | null;
+  apiKey?: string | null;
+  thinking?: string | null;
+  reasoningEffort?: string | null;
+  models?: ProviderModelView[];
+  expectedRevision?: number;
+}
+interface CustomProviderCreate {
+  id: string;
+  displayName?: string;
+  baseURL: string;
+  api: string;
+  apiKey?: string;
+  models: ProviderModelView[];
+  expectedRevision?: number;
+}
+interface CustomProviderCapability {
+  available: boolean;
+  protocols: string[];
+  revision?: 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
+/**
+ * Prompt content a 0.2.x Host accepts — mirrors its `PromptContentPart` union.
+ *
+ * 权威定义在 `chat-adapter.ts`（协议层），这里只是复用它，避免两处各写一遍
+ * 然后悄悄漂移。
+ */
+type PromptContentPartLike = PromptContentPart;
+/**
+ * `ctx.fileUploads`：内核的文件上传服务。
+ *
+ * 由内核的 `@deepseek-ai/dsh-client-file-upload` 以 cordis 服务的形式暴露，
+ * 因此插件**不需要**把字节转发到内核的 HTTP 路由（那条路由只绑 loopback，手机也到不了）。
+ */
+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;
+  };
+}
+/**
+ * `ctx.attachments`：内核的附件存储。
+ *
+ * 为什么会话里的图片必须经由它：消息**发送时**图片是 base64 内联的，但**存进历史后**
+ * 会变成 `{type:'image', attachment:{attachmentId:'sha256:…'}}` 这样的引用 ——
+ * 字节在附件存储里，不在事件里。客户端只拿到 id，所以必须有一步「按 id 取字节」，
+ * 否则历史里的图片一律显示不出来。
+ */
+interface AttachmentStoreLike {
+  readImage(ref: {
+    attachmentId: string;
+  }, signal?: AbortSignal): Promise<{
+    ref: {
+      mediaType: string;
+    };
+    data: Uint8Array;
+  }>;
+}
+interface SessionControllerLike {
+  list(request: {
+    cursor?: string;
+  }, signal: AbortSignal): Promise<{
+    items: readonly unknown[];
+  }>;
+  create(request: {
+    workspaceId?: string;
+    cwd?: string;
+    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;
+  }>;
+  cancel(request: {
+    sessionId: string;
+  }): {
+    accepted: true;
+  };
+  rename(request: {
+    sessionId: string;
+    title: string;
+  }): Promise<{
+    title: string;
+    seq: number;
+  }>;
+  fork(request: {
+    sessionId: string;
+    atSeq?: number;
+  }): Promise<{
+    sessionId: string;
+  }>;
+  selectModel(request: {
+    sessionId: string;
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+  }): Promise<{
+    selected: unknown;
+  }>;
+  /**
+   * 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.
+   */
+  modelCatalog(): Promise<{
+    default?: unknown;
+    routableProviders?: readonly string[];
+    groups?: readonly unknown[];
+    failures?: readonly {
+      id?: unknown;
+      name?: unknown;
+      message?: unknown;
+    }[];
+  }>;
+  /**
+   * 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`).
+   */
+  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;
+  }>;
+  rename(request: {
+    workspaceId: string;
+    title: string;
+  }): Promise<unknown>;
+  delete(request: {
+    workspaceId: string;
+  }): Promise<{
+    deleted: boolean;
+  }>;
+  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[]>;
+}
+/** 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`）；会话历史里的图片要经它取字节。
+   *
+   * 必须是**已经取到的服务对象**，不能是 `ctx` 本身：cordis 的注入属性是有生命周期的
+   * 惰性访问器，只在 `apply` 执行期间可读。把它存进 `host` 里、等到 HTTP 请求回调
+   * （`readAttachment`）里再读，就会撞上
+   * `cannot get property "attachments" without inject` —— 请求链路本身没问题，
+   * 挂在服务端、而且只在真的去取图时才炸，所以很难在本地测出来。
+   */
+  attachments: AttachmentStoreLike;
+  /**
+   * Kernel file-upload service (`ctx.fileUploads`).
+   *
+   * 为什么用它而不是内核那条 `/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.
+   */
+  on(event: string, listener: (...args: any[]) => unknown): () => void;
+}
+//#endregion
+//#region src/host/rate-limit.d.ts
+declare class FixedWindowLimiter {
+  private readonly limit;
+  private readonly windowMs;
+  private readonly buckets;
+  constructor(limit: number, windowMs: number);
+  consume(key: string): void;
+  private sweep;
+}
+//#endregion
+//#region src/host/auth.d.ts
+declare class AuthService {
+  private readonly database;
+  private readonly authFailures;
+  readonly pairingAttempts: FixedWindowLimiter;
+  readonly requests: FixedWindowLimiter;
+  constructor(database: WorkspaceDatabase);
+  principal(req: IncomingMessage, options?: {
+    allowAdmin?: boolean;
+  }): Principal;
+  requireAdmin(req: IncomingMessage): Principal;
+  requireScope(principal: Principal, scope: DeviceScope): void;
+  requireRoot(principal: Principal, rootId: string): void;
+}
+//#endregion
+//#region src/host/event-bus.d.ts
+declare class WorkspaceEventBus {
+  private readonly listeners;
+  emit(event: WorkspaceEvent): void;
+  subscribe(listener: (event: WorkspaceEvent) => void): () => void;
+}
+//#endregion
+//#region src/host/file-service.d.ts
+interface DirectoryPage {
+  path: string;
+  entries: FileEntryView[];
+  nextCursor?: string;
+}
+interface ContentDescriptor {
+  absolutePath: string;
+  size: number;
+  modifiedAt: number;
+  etag: string;
+  contentType: string;
+}
+interface TrashView {
+  id: string;
+  rootId: string;
+  path: string;
+  kind: string;
+  size: number;
+  createdAt: number;
+  status: string;
+}
+type EventSink = (event: WorkspaceEvent) => void;
+declare class FileService {
+  private readonly database;
+  private readonly emit;
+  constructor(database: WorkspaceDatabase, emit: EventSink);
+  list(root: StoredRoot, relativePath: string, limit?: number, cursor?: string): Promise<DirectoryPage>;
+  inspectContent(root: StoredRoot, relativePath: string): Promise<ContentDescriptor>;
+  streamContent(descriptor: ContentDescriptor, range?: {
+    start: number;
+    end: number;
+  }): import("fs").ReadStream;
+  writeContent(root: StoredRoot, relativePath: string, content: Uint8Array, conditions: {
+    ifMatch?: string;
+    ifNoneMatch?: string;
+  }): Promise<{
+    etag: string;
+    size: number;
+    modifiedAt: number;
+  }>;
+  createEntry(root: StoredRoot, relativePath: string, kind: 'file' | 'directory'): Promise<FileEntryView>;
+  moveEntry(root: StoredRoot, sourcePath: string, destinationPath: string): Promise<void>;
+  trashEntry(root: StoredRoot, relativePath: string): Promise<TrashView>;
+  listTrash(rootIds?: ReadonlySet<string>): TrashView[];
+  restoreTrash(root: StoredRoot, trashId: string): Promise<void>;
+  purgeTrash(trashId: string): Promise<void>;
+  private notify;
+}
+//#endregion
+//#region src/host/router.d.ts
+interface RemoteOperationView {
+  id: string;
+  state: 'pending' | 'succeeded' | 'failed';
+  targetHost: string;
+  targetPort: number;
+  code?: string;
+  message?: string;
+  pairingCode?: string;
+  pairingExpiresAt?: number;
+}
+interface RemoteControl {
+  status(operationId?: string): {
+    host: string;
+    port: number;
+    configuredHost: string;
+    configuredPort: number;
+    remoteEnabled: boolean;
+    operation?: RemoteOperationView;
+  };
+  enable(rootIds: string[], scopes: DeviceScope[]): RemoteOperationView;
+  disable(): RemoteOperationView;
+  configure(host: string, port: number): RemoteOperationView;
+}
+interface RouterOptions {
+  database: WorkspaceDatabase;
+  auth: AuthService;
+  files: FileService;
+  chat: DshChatAdapter;
+  settings: DshSettingsAdapter;
+  remote: RemoteControl;
+  maxUploadBytes: number;
+}
+declare class ApiRouter {
+  private readonly options;
+  constructor(options: RouterOptions);
+  handle(req: IncomingMessage, res: ServerResponse, stripPrefix?: string): Promise<void>;
+  private dispatch;
+  private dispatchManagement;
+  private dispatchEntries;
+  private dispatchContent;
+  private requireRoot;
+  private authorizedRoots;
+  private audit;
+  private readIdempotent;
+  private saveIdempotent;
+}
+//#endregion
+//#region src/host/server.d.ts
+interface RemoteApiServerOptions {
+  port: number;
+  remoteHost?: string;
+  database: WorkspaceDatabase;
+  auth: AuthService;
+  chat: DshChatAdapter;
+  events: WorkspaceEventBus;
+  handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+}
+declare class RemoteApiServer implements RemoteControl {
+  private readonly options;
+  private server;
+  private host;
+  private actualPort;
+  private configuredHost;
+  private configuredPort;
+  private remoteEnabled;
+  private readonly operations;
+  private readonly sockets;
+  private readonly webSockets;
+  private readonly eventsAbort;
+  private unsubscribeEvents;
+  private broadcastQueue;
+  private changing;
+  constructor(options: RemoteApiServerOptions);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  status(operationId?: string): {
+    operation?: RemoteOperationView;
+    host: string;
+    port: number;
+    configuredHost: string;
+    configuredPort: number;
+    remoteEnabled: boolean;
+  };
+  enable(rootIds: string[], scopes: DeviceScope[]): RemoteOperationView;
+  disable(): RemoteOperationView;
+  configure(host: string, port: number): RemoteOperationView;
+  private scheduleChange;
+  private performChange;
+  private rebind;
+  private bind;
+  private createBoundServer;
+  private closeCurrent;
+  private handleUpgrade;
+  private broadcast;
+  private eventAllowed;
+  private trimOperations;
+}
+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;
+//#endregion
+//#region src/index.d.ts
+/**
+ * 插件身份。
+ *
+ * 2.0.4 起由 `dsh-workspace` 改名为 `dsh-remote-bridge`：插件实际承担的是
+ * 「把 DSH 内核的私有 remote 协议翻译成版本化 REST，供手机端远程访问这台机器」，
+ * 外加一个设置中心（根目录 / 远程访问 / 设备 / 回收站 / 审计）。原先的
+ * 「workspace」只是其中一页，名字比内容宽。
+ *
+ * **以下一处刻意不改**，它是已发布客户端依赖的对外契约，改了等于破坏兼容：
+ * - REST 前缀 `/dsh-workspace-api`（`src/host/server.ts`）
+ *
+ * 已发布的 App 把它写死了，改名只动「装的时候叫什么、bundle 叫什么」。
+ *
+ * 另外两项**已随 2.2.0 删除独立页一并退役**，不再是契约：独立页路径 `/dsh-workspace`
+ * （页面已删）、浏览器存储键 `dsh-workspace-device-token`（只被那个页面读写过，现已无人使用）。
+ * 另有一项契约不在此处：状态目录 `dshHomePath('dsh-workspace')`（在 `cordis.patch.yml`），
+ * 换目录等于清空用户的授权根与回收站。
+ */
+declare const name = "dsh-remote-bridge";
+/**
+ * Host services this plugin needs, for DSH 0.2.x.
+ *
+ * DSH ≤ 0.1.1 published the client-shaped `apiProxy` facade from
+ * `@deepseek-ai/dsh-host-apiproxy`. DSH 0.1.2-alpha.3 replaced that package with
+ * `@deepseek-ai/dsh-api-gateway` (service `typertGateway`), which publishes no
+ * `apiProxy` — the controllers instead register directly as host services.
+ * Injecting those keeps the plugin loadable on 0.2.x, and
+ * `./host/dsh-0.2-bridge.ts` rebuilds the old facade on top of them so the
+ * chat/settings adapters keep their original contract.
+ */
+declare const inject: string[];
+interface Config {
+  dataDir?: string;
+  port?: number;
+  remoteHost?: string;
+  maxUploadBytes?: number;
+}
+interface HostContext extends Dsh02HostServices {
+  webServer: Parameters<typeof attachEmbeddedRoutes>[0];
+  agents: NonNullable<ConstructorParameters<typeof DshChatAdapter>[2]>['agents'];
+  commands: NonNullable<ConstructorParameters<typeof DshChatAdapter>[2]>['commands'];
+  logger: {
+    info(message: string): void;
+    warn(error: Error): void;
+  };
+  effect(register: () => (() => void | Promise<void>), label?: string): void;
+}
+declare function apply(ctx: HostContext, config?: Config): Promise<void>;
+//#endregion
+export { Config, apply, apply as default, inject, name };