@dshfly/remote-connector 0.2.1

package/core/dsh-web.js

@@ -0,0 +1,556 @@
+// packages/remote-connector/core/dsh-web.js
+// DSH web 0.1.2-rc.1 进程内适配层（connector 是 dsh web 的 cordis 插件，同进程）。
+//
+// 背景（2026-09 升级）：DSH 升级后 /api 协议结构性改动：
+//   · 所有 /api/* 与事件 upgrade 要求 browser-session 签名 cookie（裸请求 401）→ 不再走 HTTP，
+//     改进程内直接调 DSH 的 typertGateway 服务（天然免认证）。
+//   · 端点从点号改斜杠 + 多处改名/删除：host.describe→settings/describe、session.models→
+//     session/modelCatalog、session.history→session/page(+follow)、workspace.list→workspace/follow
+//     (流 baseline)、agentPreset.*→agentPresets.*、
+//   · payload 必须是单一 { args: {...} } 字段（旧手机端发扁平 payload）。
+//   · /api/respond 被移除（审批/提问改 waterfall + $events/result）。
+//
+// 本模块把【手机端稳定协议】翻译成【进程内 DSH DSL】：
+//   - invoke(method, payload)：点号/改名映射 + {args} 包装 → typertGateway.invokeRpc(...)
+//   - workspaceList()：由 workspace/follow 流 baseline 合成旧版 workspace.list 响应
+//   - events：进程内 cordis 事件（api-session/*, approval/request, user-questions/request）→
+//     手机端 server-request 帧
+//   - resolveApproval/resolveQuestion：把手机端 respond 结果结算为 waterfall 结果
+//
+// 纯翻译函数（mapInvoke / buildEventFrames / buildApprovalResult）可单测；gateway 与 ctx
+// 依赖注入（测试注入 mock，生产传 Cordis 真服务）。
+
+const LEGACY_OK_FIELD = Symbol('ok');
+
+/** 生成 requestId（DSH session/prompt 必填字段；手机端未发时由 connector 补一个）。 */
+export function makeRequestId() {
+  try {
+    return globalThis.crypto?.randomUUID?.() ?? `req-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+  } catch {
+    return `req-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+  }
+}
+
+/** 单字段 payload → DSH 要求的 { args: {...} }。非对象/已含 args → 原样（避免重复包装）。 */
+export function wrapArgs(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return { args: {} };
+  if ('args' in payload && typeof payload.args === 'object' && payload.args !== null) return payload;
+  return { args: payload };
+}
+
+/**
+ * 映射手机端点号/旧名 → DSH 端点（斜杠）+ 该端点的 {args} 结构（参数名键控）。
+ * 参数结构经对本机 dsh web 0.1.2-rc.1 实测确认：
+ *   · session/list → { _request:{} }   （入参名 _request）
+ *   · 多数 session.*、workspace.* → { request:{...} } （单 request 对象参数）
+ *   · session/modelCatalog、settings/describe、agentPresets/list → {}（无参）
+ * 返回 { endpoint, args } | { synthesizeWorkspaceList:true } | null（未知）。纯函数，可单测。
+ */
+export function mapInvoke(legacyMethod, payload) {
+  const p = payload || {};
+  const req = (fields) => ({ request: fields });
+  switch (legacyMethod) {
+    // host.describe：新 DSH 无 host 命名空间（settings/describe 只有 writable/hasDocument/namespaces，
+    // 无 version/cwd）→ 由 adapter 合成 { version, cwd, home }（version 读 DSH 包、cwd=进程 cwd）。
+    case 'host.describe': return { synthesizeHostInfo: true };
+
+    case 'session.list': return { endpoint: 'session/list', args: { _request: {} } };
+    case 'session.create': return { endpoint: 'session/create', args: req({
+      ...(p.sessionId != null ? { sessionId: p.sessionId } : {}),
+      ...(p.workspaceId != null ? { workspaceId: p.workspaceId } : {}),
+      ...(p.cwd != null ? { cwd: p.cwd } : {}),
+      ...(p.agentPreset != null ? { agentPreset: p.agentPreset } : {}),
+    }) };
+    case 'session.prompt': return { endpoint: 'session/prompt', args: req({
+      sessionId: p.sessionId,
+      requestId: p.requestId,
+      content: p.content,
+      ...(p.mode != null ? { mode: p.mode } : {}),
+      ...(p.clientTimeZone != null ? { clientTimeZone: p.clientTimeZone } : {}),
+    }) };
+    case 'session.cancel': return { endpoint: 'session/cancel', args: req({ sessionId: p.sessionId }) };
+    case 'session.search': return { endpoint: 'session/search', args: req({ query: p.query }) };
+    case 'session.rename': return { endpoint: 'session/rename', args: req({ sessionId: p.sessionId, title: p.title }) };
+    case 'session.selectModel': return { endpoint: 'session/selectModel', args: req({
+      sessionId: p.sessionId, provider: p.provider, model: p.model,
+      ...(p.reasoningEffort != null ? { reasoningEffort: p.reasoningEffort } : {}),
+    }) };
+    case 'session.attachment': return { endpoint: 'session/attachment', args: req({ sessionId: p.sessionId, attachmentId: p.attachmentId }) };
+    case 'session.models': return { endpoint: 'session/modelCatalog', args: {} }; // 实测：无参
+    // session.history → session/page：旧 {sessionId, maxMessages?, beforeSeq?} → 新 page request。
+    // ⚠️ 实测（本机 dsh web 0.1.2-rc.1）：session/page 的 request.throughSeq **必填**且须 ≥-1 的安全整数；
+    // -1 是"最新尾页"哨兵（source: dsh-api-session-controller validatePageRequest + page 的
+    // `throughSeq === -1 ? -1`）。手机端 history 不传 throughSeq → 默认 -1（最新）。
+    case 'session.history': return {
+      endpoint: 'session/page',
+      args: req({
+        address: { kind: 'session', sessionId: p.sessionId },
+        throughSeq: Number.isSafeInteger(p.throughSeq) ? p.throughSeq : -1,
+        ...(Number.isSafeInteger(p.beforeSeq) ? { beforeSeq: p.beforeSeq } : {}),
+        ...(Number.isSafeInteger(p.maxMessages) ? { maxMessages: p.maxMessages } : {}),
+      }),
+    };
+
+    case 'workspace.create': return { endpoint: 'workspace/create', args: req({ path: p.path }) };
+    case 'workspace.list': return { synthesizeWorkspaceList: true };
+
+    case 'agentPreset.list': return { endpoint: 'agentPresets/list', args: {} };
+    // agentPresets/select 实测：实参**直接** {agentId, agentPreset}（不包 request；包了报
+    // `unexpected "request"`），返回**字符串** preset id（app 读 r.agentPreset → 由 translateResult 包装）。
+    case 'agentPreset.select': return {
+      endpoint: 'agentPresets/select',
+      args: { agentId: p.sessionId ?? p.agentId ?? p.agent, agentPreset: p.agentPreset ?? p.id },
+    };
+
+    // commands/execute：手机端 client 已用**斜杠**（call('commands/execute', …)），payload 为
+    // { args: { agentId, line, images } }。process 内直接作为 gateway 的 args（agentId 为参数键，
+    // 实测为 agentId 而非 agent）。同时兜住历史点号写法。
+    case 'commands.execute':
+    case 'commands/execute': {
+      const inner = p?.args ?? p;
+      return { endpoint: 'commands/execute', args: inner };
+    }
+    default:
+      return null;
+  }
+}
+
+/* eslint-disable camelcase */
+/**
+ * 把 typertGateway 的 {ok:true,value}|{ok:false,error} 转成手机端可回传的结果。
+ * 手机端 server-response 信封已在 connector-core 组装；此处只看 ok/error。
+ */
+export function fromRpc(result) {
+  return { ok: !!result?.ok, value: result?.value, error: result?.error };
+}
+
+/**
+ * workspace/follow 流的 baseline → 手机端旧版 workspace.list 响应 value {items, archivedSessionIds}。
+ * workspaceView 的 path 即手机端允许根。纯函数，可单测。
+ */
+export function buildWorkspaceList(baseline) {
+  const b = baseline || {};
+  const items = (b?.value?.items || []).map((w) => ({
+    workspaceId: w?.workspaceId,
+    path: w?.path,
+    title: w?.title,
+    sessionIds: w?.sessionIds || [],
+    updatedAt: w?.updatedAt,
+    createdAt: w?.createdAt,
+  }));
+  return { items, archivedSessionIds: b?.value?.archivedSessionIds || [] };
+}
+/* eslint-enable camelcase */
+
+/**
+ * 进程内 cordis emit 事件 → 手机端 server-request 帧（method 即手机端消费名）。
+ * 返回帧数组；空数组表示无消费。纯函数，可单测。
+ */
+export function buildEventFrames({ event, args, rpcId }) {
+  if (!event || !rpcId) return [];
+  const frame = (method, payload) => ({ type: 'server-request', rpcId, method, payload });
+  switch (event) {
+    case 'api-session/added': {
+      const s = args?.[0] || {};
+      return [frame('session/added', { sessionId: s.sessionId, summary: s })];
+    }
+    case 'api-session/removed':
+      return [frame('session/removed', { sessionId: args?.[0] })];
+    case 'api-session/status':
+      // 手机端 host/session-status 帧：会话运行状态翻转（running true/false）
+      return [frame('host/session-status', { sessionId: args?.[0], running: args?.[1] === true })];
+    case 'api-session/error':
+      return [frame('session/error', { sessionId: args?.[0], message: args?.[1] })];
+    case 'api-session/activity':
+      // 活动信号不单独成帧（手机端靠 follow 流拿消息级事件）；此处仅返回空。
+      return [];
+    default:
+      return [];
+  }
+}
+
+/**
+ * 手机端 respond 结果 → waterfall 结算 outcome（近似 $events/result 语义）。
+ * approval: outcome ∈ 'allowed-once'|'rejected'|'cancelled'|'unavailable'
+ * question: answer 字符串（或 {answers:[...]}）。
+ * 返回 { kind:'result', value } | { kind:'rejected', error }。纯函数，可单测。
+ */
+export function buildApprovalResult(kind, outcome) {
+  if (kind === 'question') {
+    if (outcome === 'cancelled') {
+      return { kind: 'rejected', error: { name: 'Error', message: 'the user cancelled ask_user_question', code: 'cancelled', details: {} } };
+    }
+    const answers = typeof outcome === 'object' && outcome?.answers ? outcome.answers : [{ id: '0', selected: [String(outcome)] }];
+    return { kind: 'result', value: { answers } };
+  }
+  // approval：旧手机端 'allow'→allowed-once；'deny'/'rejected'→rejected；'cancelled'→cancelled
+  switch (String(outcome)) {
+    case 'deny':
+    case 'rejected':
+      return { kind: 'result', value: 'rejected' };
+    case 'cancelled':
+      return { kind: 'result', value: 'cancelled' };
+    default:
+      return { kind: 'result', value: 'allowed-once' };
+  }
+}
+
+/**
+ * $events 流的 waterfall 帧 → 手机端审批/提问 requested 帧。纯函数，可单测。
+ * rpcId 由调用方生成（connector 用于和手机端 respond 关联）。
+ */
+export function buildWaterfallFrame({ event, eventId, agentId, request, rpcId }) {
+  if (event === 'approval/request') {
+    return {
+      type: 'server-request', rpcId, method: 'approval/requested',
+      payload: {
+        sessionId: agentId,
+        approvalId: eventId,
+        toolName: request?.toolName ?? null,
+        callId: request?.callId ?? null,
+        reason: request?.reason ?? null,
+      },
+    };
+  }
+  if (event === 'user-questions/request') {
+    return {
+      type: 'server-request', rpcId, method: 'question/requested',
+      payload: {
+        sessionId: agentId,
+        questions: request?.questions || [],
+      },
+    };
+  }
+  return null;
+}
+
+/** waterfall 被结算（$events cancel 帧）→ 手机端 resolved 帧。纯函数，可单测。
+ *  必须带 sessionId（手机端 resolved 分支按 sid 清除卡片）+ approvalId/questionRpcId
+ *  （connector 的 PendingApprovalCache 按这些 key 剪枝）。 */
+export function buildResolvedFrame(kind, rpcId, { sessionId, eventId } = {}) {
+  const payload = { sessionId: sessionId ?? null };
+  if (kind === 'question') payload.questionRpcId = rpcId;
+  else payload.approvalId = eventId ?? rpcId;
+  return {
+    type: 'server-request', rpcId,
+    method: kind === 'question' ? 'question/resolved' : 'approval/resolved',
+    payload,
+  };
+}
+
+/**
+ * session/follow 流的一个 item → 手机端帧数组。纯函数，可单测。
+ *  - snapshot：仅取 projections（手机端已用 session/history→page 载入 records，避免重放重复）
+ *  - event：→ session/event 帧（消息级实时）
+ *  - 其余 item 忽略（返回 []）。
+ */
+export function buildSessionStreamFrames(item, sessionId, rpcId) {
+  if (!item || !rpcId) return [];
+  const frame = (method, payload) => ({ type: 'server-request', rpcId, method, payload });
+  if (item.type === 'snapshot') {
+    const frames = [];
+    if (item.projections) frames.push(frame('session/projection', { sessionId, projections: item.projections }));
+    return frames;
+  }
+  if (item.type === 'event') {
+    return [frame('session/event', { sessionId, event: item.event })];
+  }
+  return [];
+}
+
+/**
+ * 手机端会话历史读取的新旧结果形状差异翻译。
+ * 新 DSH session/page 返回 { records, hasMore }（record = {type:'event'|'chunks', event}）；
+ * 手机端（@dshfly/client 不变）读 hist.events + hist.hasMore，且每个 entry 用 e.event。
+ * records 的元素已带 .event → 直接改名 records→events 即可。纯函数，可单测。
+ */
+export function translateResult(method, value) {
+  if (method === 'session.history' && value && Array.isArray(value.records)) {
+    return { events: value.records, hasMore: value.hasMore };
+  }
+  // session.list：新 DSH 把 agentPreset/modelSelection 等放进 projections.values；手机端读取
+  // row.agentPreset（顶层）。把投影里的 agentPreset 提到顶层，保证"工作模式"显示。
+  if (method === 'session.list' && value && Array.isArray(value.items)) {
+    for (const it of value.items) {
+      const pv = it?.projections?.values;
+      if (pv?.agentPreset != null && it.agentPreset == null) it.agentPreset = pv.agentPreset;
+    }
+  }
+  // agentPresets/select：实测返回**字符串** preset id；app 读 r.agentPreset → 包装成 {agentPreset}。
+  if (method === 'agentPreset.select' && typeof value === 'string') {
+    return { agentPreset: value };
+  }
+  return value;
+}
+
+/**
+ * 适配器工厂：封装进程内 DSH 调用 + 事件订阅 + 审批结算。
+ * gateway：{ invokeRpc(endpoint, payload, signal), stream(request) }（typertGateway 服务）
+ * ctx：Cordis 上下文（on/waterfall），可选（事件订阅用；测试注入 mock）。
+ */
+export function createDshAdapter({ gateway, ctx, dshVersion = null, connectorVersion = null }) {
+  // gateway 允许传对象或返回对象的惰性函数（Cordis 服务激活时序：typertGateway 依赖 connection，
+  // 可能晚于只有 webServer 依赖的 connector apply——惰性解析确保请求时拿到最新服务实例）。
+  const gw = () => (typeof gateway === 'function' ? gateway() : gateway);
+  return {
+    _clientId: null,
+    _pendingByEvent: new Map(), // eventId -> { rpcId, event, kind, clientId }
+    _pendingByRpc: new Map(),   // rpcId  -> { eventId, event, kind, clientId }
+
+    /** 手机端点号 method + 扁平 payload → 进程内 DSH 调用。返回 {ok,value}|{ok,error}。 */
+    async invoke(method, payload) {
+      const mapped = mapInvoke(method, payload);
+      if (!mapped) return { ok: false, error: { code: 'unknown-method', message: `dshfly: unknown DSH method ${method}`, details: {} } };
+      if (mapped.synthesizeWorkspaceList) return this.workspaceList();
+      if (mapped.synthesizeHostInfo) return { ok: true, value: this.hostInfo() };
+      const g = gw();
+      if (!g?.invokeRpc) return { ok: false, error: { code: 'no-gateway', message: 'dsh adapter: typertGateway unavailable', details: {} } };
+      // session.history→session/page：throughSeq 必填且 ≤ 游标；手机端不传 → 解析最新游标
+      // （-1 是空页哨兵而非"最新"；用 MAX_INT 触发"past cursor N"再取 N 重试，冷安全、确定一次重试）。
+      if (method === 'session.history' && mapped.endpoint === 'session/page') {
+        const req = mapped.args.request;
+        const throughSeq = (Number.isSafeInteger(req.throughSeq) && req.throughSeq >= 0)
+          ? req.throughSeq
+          : await this._latestCursor(req.address?.sessionId);
+        const args = { request: { ...req, throughSeq } };
+        const r = await g.invokeRpc('session/page', { args });
+        if (!r?.ok) return r;
+        return { ok: true, value: translateResult('session.history', r.value) };
+      }
+      // session.prompt：requestId 必填（实测契约），手机端未发 → 补生成一个（mode:'queue' 已实测有效）
+      if (method === 'session.prompt' && mapped.endpoint === 'session/prompt' && !mapped.args.request?.requestId) {
+        mapped.args.request.requestId = makeRequestId();
+      }
+      // session.models → session/modelCatalog（全局、无 current）。手机端读 m.current 作为会话当前模型：
+      // 从会话投影 modelSelection.lastUsed 补 current（回退 default）。
+      if (method === 'session.models' && mapped.endpoint === 'session/modelCatalog') {
+        const cat = await g.invokeRpc('session/modelCatalog', { args: {} });
+        if (!cat?.ok) return cat;
+        if (cat.value && !cat.value.current) {
+          cat.value.current = (await this._sessionModel(payload?.sessionId)) ?? cat.value.default ?? null;
+        }
+        return { ok: true, value: cat.value };
+      }
+      const r = await g.invokeRpc(mapped.endpoint, { args: mapped.args });
+      if (!r?.ok) return r;
+      const value = translateResult(method, r.value);
+      return { ok: true, value };
+    },
+
+    /** 最新页游标：MAX_INT 探测 → 解析 "past cursor N" 里的当前游标。失败回退 0。 */
+    async _latestCursor(sessionId) {
+      if (!sessionId) return 0;
+      const g = gw();
+      if (!g?.invokeRpc) return 0;
+      try {
+        const probe = await g.invokeRpc('session/page', {
+          args: { request: { address: { kind: 'session', sessionId }, throughSeq: Number.MAX_SAFE_INTEGER, maxMessages: 1 } },
+        });
+        if (probe?.ok) return Number.MAX_SAFE_INTEGER;
+        const m = /past cursor (\d+)/.exec(String(probe?.error?.message || ''));
+        if (m) return Number(m[1]);
+      } catch {}
+      return 0;
+    },
+
+    /** 会话当前模型：从 session/list 对应行的投影 modelSelection 取（lastUsed 优先，次 next）。 */
+    async _sessionModel(sessionId) {
+      if (!sessionId) return null;
+      const g = gw();
+      if (!g?.invokeRpc) return null;
+      try {
+        const list = await g.invokeRpc('session/list', { args: { _request: {} } });
+        const item = (list?.value?.items || []).find((i) => i.sessionId === sessionId);
+        const ms = item?.projections?.values?.modelSelection;
+        return ms?.lastUsed ?? ms?.next ?? null;
+      } catch {
+        return null;
+      }
+    },
+
+    /** 由 workspace/follow baseline 合成旧版 workspace.list 响应。 */
+    async workspaceList() {
+      const g = gw();
+      if (!g?.stream) return { ok: false, error: { code: 'no-gateway', message: 'dsh adapter: typertGateway.stream unavailable', details: {} } };
+      try {
+        const controller = new AbortController();
+        const iter = await g.stream({ namespace: 'workspace', method: 'follow', args: {}, signal: controller.signal });
+        const first = await iter.next(); // 取 baseline
+        controller.abort();
+        if (first.done || !first.value) throw new Error('workspace/follow produced no baseline');
+        return { ok: true, value: buildWorkspaceList(first.value) };
+      } catch (e) {
+        return { ok: false, error: { code: 'workspace-list-failed', message: e?.message || String(e), details: {} } };
+      }
+    },
+
+    /**
+     * 合成 host.describe 响应（2026-09：新 DSH 无 host 命名空间）。手机端工作区详情页读
+     * host.version（DSH 版本）与 host.cwd（主机工作目录）。version 取传入的 DSH 包版本
+     * （index.js resolveDshVersion），cwd 取 dsh web 进程 cwd，home 兜底。
+     */
+    hostInfo() {
+      return {
+        version: typeof dshVersion === 'function' ? dshVersion() : (dshVersion ?? null),
+        // 本连接器插件（@dshfly/remote-connector）自身版本 —— 运行中已安装包的版本。
+        connectorVersion: connectorVersion ?? null,
+        cwd: typeof process !== 'undefined' ? (process.cwd?.() ?? null) : null,
+        home: typeof process !== 'undefined' ? (process.env?.HOME || null) : null,
+      };
+    },
+
+    /**
+     * 订阅进程内 cordis 事件并按映射推送（emit 事件直接映射；waterfall 由
+     * subscribeApproval/subscribeQuestion 单独结算）。
+     * onFrames: (frames:[]) => void。
+     */
+    subscribeEvents(onFrames) {
+      if (!ctx?.on) return () => {};
+      const disposers = [];
+      for (const event of ['api-session/added', 'api-session/removed', 'api-session/status', 'api-session/error']) {
+        disposers.push(ctx.on(event, (...args) => {
+          let frames;
+          try {
+            frames = buildEventFrames({ event, args, rpcId: `ev-${Date.now()}-${Math.floor(Math.random() * 1e6)}` });
+          } catch { frames = []; }
+          if (frames.length) onFrames(frames);
+        }));
+      }
+      return () => { for (const d of disposers) { try { d(); } catch {} } };
+    },
+
+    resolveApproval: (outcome) => buildApprovalResult('approval', outcome),
+    resolveQuestion: (outcome) => buildApprovalResult('question', outcome),
+
+    /**
+     * 以 DSH $events 远程流客户端身份运行：接收 emit 事件 + approval/request +
+     * user-questions/request 瀑布，转成手机端帧经 onFrames 送出；瀑布由 onResolved 结算。
+     * 返回 stop()。gateway.openRemoteEvents({args:{}}, signal) 预期产出
+     * {type:'ready',clientId} / {type:'emit',event,args} / {type:'waterfall',event,eventId,agentId,request}
+     * / {type:'cancel',eventId}。
+     */
+    startEventPump({ onFrames, onResolved, onError } = {}) {
+      const g = gw();
+      if (!g?.openRemoteEvents) return () => {};
+      const controller = new AbortController();
+      let active = true;
+      let backoff = 1000;
+      let clientId = null;
+      let pendingByEvent = this._pendingByEvent;
+      let pendingByRpc = this._pendingByRpc;
+      const rand = () => `rpc-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+
+      const pump = async () => {
+        while (active && !controller.signal.aborted) {
+          try {
+            const iter = await g.openRemoteEvents({ args: {} }, controller.signal);
+            // 每次开流先消费 opening ready（有的实现首帧即 ready；跳过非 ready 直到遇到）
+            for await (const frame of iter) {
+              if (!active) break;
+              if (frame?.type === 'ready') { clientId = frame.clientId; continue; }
+              if (frame?.type === 'emit') {
+                const frames = buildEventFrames({ event: frame.event, args: frame.args, rpcId: rand() });
+                if (frames.length) onFrames?.(frames);
+                continue;
+              }
+              if (frame?.type === 'waterfall') {
+                const kind = frame.event === 'user-questions/request' ? 'question' : frame.event === 'approval/request' ? 'approval' : null;
+                if (!kind) continue;
+                const rpcId = rand();
+                const rec = { rpcId, eventId: frame.eventId, event: frame.event, kind, clientId, sessionId: frame.agentId ?? null };
+                pendingByEvent.set(frame.eventId, rec);
+                pendingByRpc.set(rpcId, rec);
+                const phoneFrame = buildWaterfallFrame({ event: frame.event, eventId: frame.eventId, agentId: frame.agentId, request: frame.request, rpcId });
+                onFrames?.([phoneFrame]);
+                continue;
+              }
+              if (frame?.type === 'cancel') {
+                const rec = pendingByEvent.get(frame.eventId);
+                if (rec) {
+                  pendingByEvent.delete(frame.eventId);
+                  pendingByRpc.delete(rec.rpcId);
+                  onResolved?.(buildResolvedFrame(rec.kind, rec.rpcId, { sessionId: rec.sessionId, eventId: rec.eventId }));
+                }
+              }
+            }
+            // 流结束（非主动停止）→ 退避重开
+            if (active && !controller.signal.aborted) {
+              await new Promise((r) => setTimeout(r, backoff));
+              backoff = Math.min(backoff * 2, 30000);
+            }
+          } catch (e) {
+            onError?.(e);
+            if (active && !controller.signal.aborted) {
+              await new Promise((r) => setTimeout(r, backoff));
+              backoff = Math.min(backoff * 2, 30000);
+            }
+          }
+        }
+      };
+      const task = pump();
+      return () => { active = false; try { controller.abort(); } catch {} };
+    },
+
+    /**
+     * 为专注会话开 session/follow 流，把 snapshot/event 转成手机端帧（Phase 3 消息级实时）。
+     * 返回 stop()（取消流）。同一会话重复调用/换会话由调用方先 stop 旧流。
+     */
+    startSessionFollow(sessionId, { onFrames, onError } = {}) {
+      const g = gw();
+      if (!g?.stream) return () => {};
+      const controller = new AbortController();
+      let active = true;
+      const rpcId = `sf-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+      (async () => {
+        try {
+          const iter = await g.stream({
+            namespace: 'session', method: 'follow',
+            // ⚠️ session/follow 的 args 也走 {request:{...}} 包装（实测定型：扁平 {address} 开流为空）。
+            args: { request: { address: { kind: 'session', sessionId }, maxMessages: 10 } },
+            signal: controller.signal,
+          });
+          for await (const item of iter) {
+            if (!active) break;
+            const frames = buildSessionStreamFrames(item, sessionId, rpcId);
+            if (frames.length) onFrames?.(frames);
+          }
+        } catch (e) {
+          if (!active) return;
+          onError?.(e);
+        }
+      })();
+      return () => { active = false; try { controller.abort(); } catch {} };
+    },
+
+    /**
+     * 手机端 /api/respond（client-response 信封）→ 结算对应 waterfall。
+     * message = { type:'client-response', rpcId, result:{ok,value|error} }。
+     * 返回 {ok:true}（已结算）或 {ok:false,error}（无待决项/网关缺失）。
+     */
+    async resolveRespond(message) {
+      const rpcId = message?.rpcId;
+      const rec = this._pendingByRpc.get(rpcId);
+      if (!rec) return { ok: false, error: { code: 'approval-not-found', message: '该审批/提问已结算或不存在', details: {} } };
+      if (!gw()?.dispatchRpc) return { ok: false, error: { code: 'no-gateway', message: 'dsh adapter: typertGateway unavailable', details: {} } };
+      let outcome;
+      if (rec.kind === 'question') {
+        const answer = message?.result?.value?.answer;
+        outcome = (!message?.result?.ok) || answer == null ? buildApprovalResult('question', 'cancelled') : buildApprovalResult('question', answer);
+      } else {
+        const raw = message?.result?.ok === false ? 'cancelled' : (message?.result?.value?.outcome ?? 'allow');
+        outcome = buildApprovalResult('approval', raw);
+      }
+      // ⚠️ $events/result 由网关专门的 dispatchRpc 处理（invokeRpc 会当普通业务方法解析 → 静默失败
+      // "identifies no active event stream"）。必须走 dispatchRpc。
+      const r = await gw().dispatchRpc('$events/result', { args: { clientId: rec.clientId, eventId: rec.eventId, outcome } });
+      this._pendingByEvent.delete(rec.eventId);
+      this._pendingByRpc.delete(rpcId);
+      if (!r.ok) return { ok: false, error: r.error };
+      // 手机端作为 resolver 时，网关不会向"此客户端"广播 cancel（它在 deliveries 里已被移除），
+      // 但手机 UI 仍需要 resolved 帧来按 sid 清除卡片 → 回传 resolvedFrame 由 connector 注入。
+      return { ok: true, value: undefined, resolvedFrame: buildResolvedFrame(rec.kind, rpcId, { sessionId: rec.sessionId, eventId: rec.eventId }) };
+    },
+  };
+}
+
+export { LEGACY_OK_FIELD };

package/core/keys.js

@@ -0,0 +1,68 @@
+// packages/remote-connector/core/keys.js
+// 设备密钥的加载/生成/持久化（私钥只落本机文件，权限 0600）。自 services/connector/keys.js 迁入（单一代码源）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { generateIdentityKeypair, generateTransportKeypair } from '@dshfly/crypto';
+
+export function defaultKeysFile() {
+  const dir = process.env.DSHFLY_HOME || path.join(os.homedir(), '.dshfly');
+  return path.join(dir, 'keys.json');
+}
+
+/** 自动生成的设备账号名（dev login 账号，配对的 user 隔离键）。首次生成后持久化，稳定不变。 */
+export function deviceAccountName() {
+  return 'dshfly-' + randomBytes(6).toString('hex');
+}
+
+export function loadOrCreateKeys(file = defaultKeysFile()) {
+  if (fs.existsSync(file)) {
+    const k = JSON.parse(fs.readFileSync(file, 'utf8'));
+    k.sessionKeys = k.sessionKeys || {};
+    k.outSeq = k.outSeq || 0; // 兼容旧 keys 文件
+    if (!k.accountName) {
+      k.accountName = deviceAccountName(); // D1：仅兼容旧 keys 文件（不再参与任何认证/展示）
+      saveKeys(k, file);
+    }
+    return k;
+  }
+  const id = generateIdentityKeypair();
+  const tr = generateTransportKeypair();
+  const keys = {
+    identitySecretKey: id.secretKey,
+    identityPublicKey: id.publicKey,
+    transportSecretKey: tr.secretKey,
+    transportPublicKey: tr.publicKey,
+    deviceId: null,
+    deviceToken: null,
+    accountName: deviceAccountName(),
+    sessionKeys: {},
+    outSeq: 0,
+  };
+  saveKeys(keys, file);
+  return keys;
+}
+
+// 领取并预留 outSeq 窗口：返回本次会话的起始 seq，并把持久化水位推进 reserve 个。
+// connector 重启/崩溃后，新会话从"旧水位 + reserve"开始 → 新 seq 必高于手机端
+// ReplayGuard 记住的旧水位，事件流不会静默死亡（Kimi Blocker 修复）。
+// 运行中的每次出站都用 nextOutSeq 推进并落盘（_markUsed 已有 500ms 防抖顺带持久化）。
+export function claimOutSeq(keys, file, reserve = 1000) {
+  const start = Number(keys.outSeq || 0);
+  keys.outSeq = start + reserve;
+  saveKeys(keys, file);
+  return start;
+}
+
+export function saveKeys(keys, file = defaultKeysFile()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 }); // 目录 0700（C2/P2-7）
+  fs.writeFileSync(file, JSON.stringify(keys, null, 2), { mode: 0o600 });
+  try {
+    // C2（P2-7）：writeFileSync 的 mode 只对新建文件生效——已存在文件（旧版本/恢复）
+    // 覆盖写入保持原权限（可能 0644）；每次保存后显式收紧
+    fs.chmodSync(file, 0o600);
+    fs.chmodSync(path.dirname(file), 0o700);
+  } catch {}
+}