dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/host-bridge/endpoints.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * 端点表：旧 `apiProxy.<ns>.<method>` 的键 ⇄ 宿主 wire 名与参数形状。
+ *
+ * ⚠️ 这张表是人肉对照宿主 descriptor 校验的，**没有任何机器可校验机制**，而它错一次的
+ * 后果是静默的：`sessions.projections` 曾少包一层 `request`，宿主每次都回 400，
+ * 而 App 侧把 400 catch 掉了，于是整个统计 UI 凭空消失。args 的键名必须**恰好**是
+ * descriptor 的 wire 名（多一个少一个都报 gateway/arguments-invalid，dropUnexpectedArgs
+ * 只摘多余的键，救不了「少一个」）。改动前请先在 test/host-bridge-endpoints.test.cjs
+ * 里补一条参数化用例。
+ */
+
+const { invoke, invokeEnvelope, ok, fail, pick, requestId, unsupported, warn } = require('./transport.js');
+const { historyViaPage, modelCatalog, workspaceListViaFollow, subagentCatalog } = require('./shims.js');
+const { createDirectory, hostServesBrowse, listDirectory, wireError } = require('../directory-browse.js');
+
+// ── 端点表 ────────────────────────────────────────────────────────────────
+//
+// inv(namespace, method, buildArgs)：最常见的一档 —— 宿主方法只有一个 `request` 参数，
+// payload 原样塞进去即可。少数几个要改名（sessionId → agentId）、要丢字段
+// （fork 的 increaseTitle）、要补必填字段（prompt 的 requestId）。
+
+function inv(namespace, method, buildArgs) {
+  return (ctx, payload, signal) => invokeEnvelope(ctx, namespace, method, (buildArgs || ((p) => ({ request: p })))(payload), signal);
+}
+
+const ENDPOINTS = {
+  // sessions
+  // 会话列表：键名是 `_request` —— 宿主签名 `list(_request: SessionListRequest, signal)`
+  // 用下划线前缀表示「保留的空请求」，assertExactArguments 认的就是这个字面名。
+  'sessions.list': inv('session', 'list', (p) => ({ _request: p && Object.keys(p).length ? p : {} })),
+  'sessions.history': (ctx, payload, signal) => historyViaPage(ctx, payload, signal),
+  // 0.2.0 把投影从 session.page 的返回值里拆走了（page 只回 events/hasMore/cursor），
+  // 整帧 values 只能走这一个端点。
+  //
+  // args 形状由宿主 typertGateway 的 assertExactArguments 把关：键名必须**恰好**是
+  // descriptor 的 wire 名，多一个少一个都报 gateway/arguments-invalid（而
+  // dropUnexpectedArgs 只会摘多余的键，救不了「少一个」）。session/projections 的
+  // descriptor 只有一个参数，wire 名是 `request`，内层是 `object({ sessionId })`
+  // （app.asar 里 dsh_api_session_controller 的 session.projections parameter_0 schema）。
+  //
+  // 这里曾经写成 `pick(p, ['sessionId'])`（注释断言「没有 request 包层」，是错的）：
+  // 少一层 request，宿主每次都回 `missing "request"` → /session/stats 恒 400。而
+  // App 侧把 400 catch 掉了（app/src/ChatScreen.tsx 的统计轮询 `catch { }`），于是
+  // **一整层 UI 静默消失**：输入框下方的统计行、ContextMeter 圆环、TodoDock、
+  // GoalBar、权限档、planMode、图片上限——它们全都来自这一个投影帧。
+  // 形状写错的代价是不报错的「功能不见了」，所以每个端点都要对着宿主 descriptor 核。
+  'sessions.projections': inv('session', 'projections', (p) => ({ request: pick(p, ['sessionId']) })),
+  'sessions.prompt': inv('session', 'prompt', (p) => ({
+    request: {
+      ...pick(p, ['sessionId', 'mode', 'content', 'clientTimeZone']),
+      requestId: typeof (p && p.requestId) === 'string' && p.requestId ? p.requestId : requestId('mobile-prompt'),
+    },
+  })),
+  'sessions.cancel': inv('session', 'cancel'),
+  'sessions.rename': inv('session', 'rename'),
+  'sessions.create': inv('session', 'create'),
+  'sessions.search': inv('session', 'search'),
+  'sessions.selectModel': inv('session', 'selectModel'),
+  'sessions.attachment': inv('session', 'attachment'),
+  'sessions.updateQueue': inv('session', 'updateQueue'),
+  // 宿主的 fork 请求体只有 sessionId / atSeq，increaseTitle 在 0.2.0 已删除。
+  'sessions.fork': inv('session', 'fork', (p) => ({ request: pick(p, ['sessionId', 'atSeq']) })),
+  // 宿主的模型目录是全局的（不再按 session 查），这里翻译成插件/移动端要的形状。
+  'sessions.models': (ctx, payload, signal) => modelCatalog(ctx, signal),
+
+  // agentPresets（namespace 是复数 agentPresets）
+  'agentPresets.list': inv('agentPresets', 'list', () => ({})),
+  'agentPresets.read': inv('agentPresets', 'read', (p) => ({ agentPreset: p && p.agentPreset })),
+  'agentPresets.select': (ctx, payload, signal) =>
+    invoke(ctx, 'agentPresets', 'select', { agentId: payload.sessionId, agentPreset: payload.agentPreset }, signal)
+      .then((r) => (r.error ? fail(r.error) : ok({ agentPreset: r.value }))),
+  'agentPresets.copy': () => unsupported('复制 agent preset 的接口'),
+  'agentPresets.remove': () => unsupported('删除 agent preset 的接口'),
+
+  // workspace
+  'workspace.list': (ctx, payload, signal) => workspaceListViaFollow(ctx, signal),
+  'workspace.create': inv('workspace', 'create'),
+  'workspace.rename': inv('workspace', 'rename'),
+  'workspace.delete': inv('workspace', 'delete'),
+  'workspace.archiveSession': inv('workspace', 'archiveSession'),
+  'workspace.unarchiveSession': inv('workspace', 'unarchiveSession'),
+  'workspace.pinSession': inv('workspace', 'pinSession'),
+  'workspace.unpinSession': inv('workspace', 'unpinSession'),
+  'workspace.insertSessionBefore': inv('workspace', 'insertSessionBefore'),
+
+  // host.* → directoryPicker.*（宿主服务 browse 时），否则回落到插件自带的 browse 原语。
+  //
+  // 为什么会有「否则」：宿主那套选择器由 directory-picker-auto 启动时二选一，只有
+  // 「web 服务绑到非回环」或「平台不是 darwin/win32」才挂 browse；无头移动宿主由本包的
+  // cordis.mobile-host.yml 钉成 browse，**桌面 profile 宿主**则解析成 native。于是
+  // 「桌面宿主 + 手机远程连」这一格没人盖 —— 手机点「添加工作区」只拿到
+  // `host.listDirectory needs the browse capability`，一个条目都列不出来。
+  // 判定与回落语义见 lib/mobile/directory-browse.js 的头注释：宿主服务 browse 就整条走
+  // 宿主（策略单一真源），宿主明确只服务 native（或查不到选择器）时用插件自己那份。
+  //
+  // 金标准（test/host-bridge-endpoints.test.cjs）钉的仍是「走宿主」那条路由：它的假 ctx
+  // 显式给了一个 browse 能力对象。
+  'host.listDirectory': (ctx, payload, signal) => (hostServesBrowse(ctx)
+    ? invokeEnvelope(ctx, 'directoryPicker', 'list', pick(payload, ['path']), signal)
+    : localListDirectory(ctx, payload, signal)),
+  'host.createDirectory': (ctx, payload, signal) => (hostServesBrowse(ctx)
+    ? invoke(ctx, 'directoryPicker', 'createDirectory', { path: payload.path, name: payload.name }, signal)
+      .then((r) => (r.error ? fail(r.error) : ok({ path: r.value })))
+    : localCreateDirectory(ctx, payload, signal)),
+
+  // skills / subagents
+  'skills.list': inv('skills', 'list'),
+  'subagents.prompt': inv('subagents', 'prompt', (p) => ({
+    request: {
+      ...pick(p, ['parentSessionId', 'childSessionId', 'mode', 'content', 'clientTimeZone']),
+      requestId: typeof (p && p.requestId) === 'string' && p.requestId ? p.requestId : requestId('mobile-subagent'),
+      delivery: (p && p.delivery) || 'queue',
+    },
+  })),
+  'subagents.interrupt': (ctx, payload, signal) =>
+    invoke(ctx, 'subagents', 'interruptByParent', {
+      childSessionId: payload.childSessionId,
+      parentSessionId: payload.parentSessionId,
+      mode: payload.mode || 'continuable',
+    }, signal).then((r) => (r.error ? fail(r.error) : ok(r.value))),
+  'subagents.list': (ctx, payload, signal) => subagentCatalog(ctx, payload, signal),
+
+  // goals：objective 被宿主挪进了 request 里
+  'goals.edit': (ctx, payload, signal) =>
+    invoke(ctx, 'goals', 'edit', {
+      agentId: payload.sessionId,
+      ref: payload.ref,
+      request: pick(payload, ['objective', 'maxGoalRounds']),
+    }, signal).then((r) => (r.error ? fail(r.error) : ok(r.value))),
+  'goals.pause': (ctx, payload, signal) => goalAction(ctx, 'pause', payload, signal),
+  'goals.resume': (ctx, payload, signal) => goalAction(ctx, 'resume', payload, signal),
+  'goals.complete': (ctx, payload, signal) => goalAction(ctx, 'complete', payload, signal),
+  'goals.clear': (ctx, payload, signal) => goalAction(ctx, 'clear', payload, signal),
+
+  // settings / llm / credentials
+  'settings.describe': inv('settings', 'describe', () => ({})),
+  'settings.mutate': inv('settings', 'mutate', (p) => pick(p, ['ns', 'ops', 'expectedRevision'])),
+  'llm.providers': (ctx, payload, signal) =>
+    invoke(ctx, 'llm', 'listProviders', {}, signal).then((r) => {
+      if (r.error) return fail(r.error);
+      const list = Array.isArray(r.value) ? r.value : [];
+      return ok({
+        providers: list.map((item) => ({
+          provider: item && item.id,
+          displayName: item && (item.name || item.id),
+          active: true,
+        })),
+      });
+    }),
+  'credentials.describe': inv('credentials', 'describe', (p) => ({ refs: p.refs })),
+  'credentials.set': inv('credentials', 'set', (p) => ({ ref: p.ref, value: p.value })),
+  'credentials.unset': inv('credentials', 'unset', (p) => ({ ref: p.ref })),
+};
+
+function goalAction(ctx, method, payload, signal) {
+  return invoke(ctx, 'goals', method, { agentId: payload.sessionId, ref: payload.ref }, signal)
+    .then((r) => (r.error ? fail(r.error) : ok(r.value)));
+}
+
+/**
+ * 宿主只服务 native 选择器时的清单条（**不回落到网关**）。
+ *
+ * 这里的 code/message 与宿主 browse 后端那条路完全同名同形：本地实现的
+ * `directory-unreadable` 等翻成 `directory-picker/unreadable` 这一组 wire 码，App 侧的
+ * `formatDirectoryError` 已经按它们写好了文案，两条路对客户端应当不可区分。
+ */
+async function localListDirectory(ctx, payload, signal) {
+  const path = payload && typeof payload.path === 'string' && payload.path.trim() ? payload.path.trim() : undefined;
+  try {
+    return ok(await listDirectory(path, { signal }));
+  } catch (error) {
+    warn(ctx, `宿主选择器不是 browse，listDirectory 走插件自带实现：${error && error.message}`);
+    return fail(wireError(error));
+  }
+}
+
+/** 宿主只服务 native 选择器时的建目录条；回创建出来的 path，与网关那条同形状。 */
+async function localCreateDirectory(ctx, payload, signal) {
+  try {
+    return ok({ path: await createDirectory(payload.path, payload.name) });
+  } catch (error) {
+    warn(ctx, `宿主选择器不是 browse，createDirectory 走插件自带实现：${error && error.message}`);
+    return fail(wireError(error));
+  }
+}
+
+module.exports = { ENDPOINTS, goalAction, localCreateDirectory, localListDirectory };

package/lib/mobile/host-bridge/event-synthesis.js

@@ -0,0 +1,232 @@
+'use strict';
+
+/**
+ * 事件合成：旧设备级 `events.mux` 的帧流 ⇄ 0.2.0 拆开的三条流。
+ *
+ * 旧 mux 一次给出「这个设备正在发生的一切」，0.2.0 没有对应端点（事件已拆成
+ * session/follow、session/control、workspace/follow），这里按 payload 里有没有 sessionId
+ * 合成同形帧：带 sessionId → 该会话的 follow + job 整帧 + 投影整帧；不带 → 设备级的
+ * 工作区基线 + 全局投影整帧。调用方（stream.js / events.js / index.js 的 mirror）本来就
+ * 按 frame.payload 里的 type 分发，形状对上了它们一行都不用改。
+ */
+
+const { openStream, warn } = require('./transport.js');
+
+// ── 事件合成 ──────────────────────────────────────────────────────────────
+
+/** 把 payload.sessionId 取出来；没有就按设备级处理。 */
+function sessionHint(request) {
+  const payload = request && request.payload;
+  const sessionId = payload && payload.sessionId;
+  return typeof sessionId === 'string' && sessionId ? sessionId : null;
+}
+
+/** 一条流跑不通不该拖垮其余流：这里把异常吃掉，只丢这一条源的帧。 */
+async function* tolerate(frames, what, ctx) {
+  try {
+    for await (const frame of frames) yield frame;
+  } catch (error) {
+    warn(ctx, `${what} 事件流中断：${error && error.message ? error.message : String(error)}`);
+  }
+}
+
+/** 单会话事件流：follow 的 live 事件（跳过 snapshot，历史走 session.history）。 */
+async function* sessionEventFrames(ctx, sessionId, signal) {
+  const frames = await openStream(ctx, 'session', 'follow', {
+    request: { address: { kind: 'session', sessionId }, maxMessages: 1 },
+  }, signal);
+  for await (const frame of tolerate(frames, `session/${sessionId}`, ctx)) {
+    if (!frame || frame.type !== 'event' || !frame.event) continue;
+    yield { payload: { type: 'session/event', sessionId, event: frame.event } };
+  }
+}
+
+/** 后台任务整帧。宿主 job/list 是流，首帧即全量 rows，之后按变化推。 */
+async function* sessionJobFrames(ctx, sessionId, signal) {
+  const frames = await openStream(ctx, 'job', 'list', { request: { sessionId } }, signal);
+  for await (const frame of tolerate(frames, `job/${sessionId}`, ctx)) {
+    if (!frame || frame.type !== 'rows') continue;
+    yield { payload: { type: 'session/jobs', sessionId, jobs: Array.isArray(frame.jobs) ? frame.jobs : [] } };
+  }
+}
+
+/**
+ * 投影整帧（排队条、计划条、目标条、模型选择等全量快照）。
+ *
+ * 宿主 session.control 是设备级投影流：首帧 baseline 一次性给出
+ * { projections: { [sessionId]: { asOfSeq, values } } }，之后是
+ * { type:'projection', sessionId, key, value, seq } 的单键更新。
+ * 旧帧是整帧（幂等全量），这里保持整帧语义 —— 更新帧就带上累积后的 values 重发。
+ */
+function projectionState() {
+  const values = new Map();   // sessionId -> { asOfSeq, values }
+  return {
+    applyBaseline(baseline) {
+      const projections = baseline && typeof baseline === 'object' ? baseline.projections : null;
+      if (!projections || typeof projections !== 'object') return [];
+      const touched = [];
+      for (const [sessionId, entry] of Object.entries(projections)) {
+        const next = {
+          asOfSeq: Number.isSafeInteger(entry && entry.asOfSeq) ? entry.asOfSeq : 0,
+          values: (entry && entry.values && typeof entry.values === 'object') ? entry.values : {},
+        };
+        values.set(sessionId, next);
+        touched.push(sessionId);
+      }
+      return touched;
+    },
+    applyUpdate(update) {
+      const sessionId = update && update.sessionId;
+      if (typeof sessionId !== 'string') return [];
+      const current = values.get(sessionId) || { asOfSeq: 0, values: {} };
+      if (typeof update.key === 'string') current.values = { ...current.values, [update.key]: update.value };
+      if (Number.isSafeInteger(update.seq)) current.asOfSeq = update.seq;
+      values.set(sessionId, current);
+      return [sessionId];
+    },
+    snapshot(sessionId) {
+      return values.get(sessionId) || null;
+    },
+    /** 全量快照的平表（sessionId → values），只读用途：投影基线要一次看全部会话。 */
+    all() {
+      return new Map(values);
+    },
+  };
+}
+
+/**
+ * 宿主投影 `inbox` → 移动端 `session/queue` 帧的**平铺 items**。
+ *
+ * 形状差是这条链上唯一的坑：宿主把 inbox 定义成按键分组的对象
+ * `{ 'next-turn': Message[], 'next-step': Message[] }`（桌面 bundle 里
+ * `@deepseek-ai/dsh-agent-loop/inbox` 的 `key: 'inbox'` + `wire.view: (state) => state`，
+ * 桌面 QueueDock 读的也正是 `inbox['next-turn']`），而移动端帧的约定是数组
+ * `[{ id, placement, message }]`（`app/src/types/chatStream.ts` 的 QueueItem、
+ * `app/src/hooks/streamFrame.ts` 的 `session/queue` 分支）。原样转发对象时 App 的
+ * `Array.isArray(items)` 判定失败、整帧被静默丢弃 —— 排队条一次都不显示。
+ *
+ * `next-turn`（等下一轮才开始的消息）→ `placement: 'queued'`，QueueDock 只认这一个值。
+ * `next-step`（本步末尾注入的插话）暂不合成 `steering`：手机发起的插话已有本地待发气泡
+ * （`useChatStream` 的 `pending-<clientMessageId>`）与落定后的正文行，多推一份会在同一处
+ * 多画一条用户气泡。`message.id` 用宿主行自己的 id，App 靠它与正文去重（chatRenderRows）。
+ */
+function queueItems(inbox, ctx) {
+  const rows = inbox && Array.isArray(inbox['next-turn']) ? inbox['next-turn'] : [];
+  const items = [];
+  let dropped = 0;
+  for (const message of rows) {
+    if (!message || typeof message !== 'object') continue;
+    const id = typeof message.id === 'string' && message.id ? message.id : '';
+    if (!id) { dropped += 1; continue; } // 没有 id 的行没法被 session.updateQueue 定位，别发出去
+    items.push({ id, placement: 'queued', message: { id, content: message.content } });
+  }
+  // 丢弃必须留痕：旧实现是裸 continue，手机上少一条待发消息而宿主侧一行日志都没有，
+  // 只能靠人对着桌面端数气泡。凭空造 id 更糟——App 的 session.updateQueue 按 id 定位，
+  // 假 id 会让「已落定」和「待发」两条记录对不上。
+  if (dropped > 0) warn(ctx, `session/queue 丢了 ${dropped} 条没有 id 的待发行（App 无法定位，手机上会少这几条）`);
+  return items;
+}
+
+async function* projectionFrames(ctx, sessionId, signal) {
+  const frames = await openStream(ctx, 'session', 'control', {}, signal);
+  const state = projectionState();
+  for await (const frame of tolerate(frames, 'session/control', ctx)) {
+    if (!frame) continue;
+    let touched = [];
+    if (frame.type === 'baseline') touched = state.applyBaseline(frame.value);
+    else if (frame.type === 'projection') touched = state.applyUpdate(frame);
+    for (const id of touched) {
+      if (sessionId && id !== sessionId) continue;
+      const current = state.snapshot(id);
+      yield { payload: { type: 'session/projection', sessionId: id, seq: current.asOfSeq, values: current.values } };
+      // 排队条按旧约定走独立的 session/queue 整帧（移动端 QueueDock 读这个类型），
+      // 宿主侧的对应投影是 inbox。
+      if (current.values && current.values.inbox !== undefined) {
+        yield { payload: { type: 'session/queue', sessionId: id, items: queueItems(current.values.inbox, ctx) } };
+      }
+    }
+  }
+}
+
+/** 设备级：工作区基线 + 全局投影（没有 sessionId 时能给的就这些）。 */
+async function* deviceFrames(ctx, signal) {
+  const workspace = await openStream(ctx, 'workspace', 'follow', {}, signal).catch(() => null);
+  if (workspace) {
+    for await (const frame of tolerate(workspace, 'workspace/follow', ctx)) {
+      if (!frame) continue;
+      if (frame.type === 'baseline' && frame.value) {
+        yield { payload: { type: 'host/workspace', ...frame.value } };
+      } else if (frame.type === 'increment' || frame.type === 'change') {
+        yield { payload: { type: 'host/workspace', ...(frame.value && typeof frame.value === 'object' ? frame.value : { change: frame }) } };
+      }
+    }
+  }
+  yield* projectionFrames(ctx, null, signal);
+}
+
+/** 旧 `events.mux`：设备级帧流，带 sessionId 时收窄成单会话视角。 */
+function muxFrames(ctx, request, signal) {
+  const sessionId = sessionHint(request);
+  return (async function* run() {
+    if (!sessionId) {
+      yield* deviceFrames(ctx, signal);
+      return;
+    }
+    const control = openStream(ctx, 'session', 'control', {}, signal).then((frames) => tolerate(frames, 'session/control', ctx));
+    const jobs = openStream(ctx, 'job', 'list', { request: { sessionId } }, signal).then((frames) => tolerate(frames, `job/${sessionId}`, ctx));
+    const follow = openStream(ctx, 'session', 'follow', {
+      request: { address: { kind: 'session', sessionId }, maxMessages: 1 },
+    }, signal).then((frames) => tolerate(frames, `session/${sessionId}`, ctx));
+    const projections = projectionState();
+    const sources = await Promise.all([control, jobs, follow].map((promise) => promise.then(async function* wrap(iterable) {
+      for await (const frame of iterable) {
+        if (frame && frame.type === 'rows') {
+          yield { payload: { type: 'session/jobs', sessionId, jobs: Array.isArray(frame.jobs) ? frame.jobs : [] } };
+        } else if (frame && frame.type === 'baseline') {
+          yield* applyBaseline(frame, projections, sessionId, ctx);
+        } else if (frame && frame.type === 'projection') {
+          yield* applyUpdate(frame, projections, sessionId, ctx);
+        } else if (frame && frame.type === 'event' && frame.event) {
+          yield { payload: { type: 'session/event', sessionId, event: frame.event } };
+        }
+      }
+    }).catch((error) => {
+      warn(ctx, `事件流中断：${error && error.message ? error.message : String(error)}`);
+      return (async function* empty() {})();
+    })));
+    const pending = new Map(sources.map((source, index) => [index, source.next()]));
+    while (pending.size > 0) {
+      const winner = await Promise.race([...pending.entries()].map(async ([index, step]) => ({ index, step: await step })));
+      if (winner.step.done) {
+        pending.delete(winner.index);
+        continue;
+      }
+      pending.set(winner.index, sources[winner.index].next());
+      yield winner.step.value;
+    }
+  })();
+}
+
+// 单会话视角下的投影合并：整条 mux 生命周期共用一个 state，否则增量帧会把
+// baseline 里的 values 冲掉（移动端把 session/projection 当整帧消费）。
+function applyBaseline(frame, state, sessionId, ctx) {
+  return projectionFramesFrom(ctx, frame, sessionId, state);
+}
+
+function applyUpdate(frame, state, sessionId, ctx) {
+  return projectionFramesFrom(ctx, frame, sessionId, state);
+}
+
+async function* projectionFramesFrom(ctx, frame, sessionId, state) {
+  const touched = frame.type === 'baseline' ? state.applyBaseline(frame.value) : state.applyUpdate(frame);
+  for (const id of touched) {
+    if (id !== sessionId) continue;
+    const current = state.snapshot(id);
+    yield { payload: { type: 'session/projection', sessionId: id, seq: current.asOfSeq, values: current.values } };
+    if (current.values && current.values.inbox !== undefined) {
+      yield { payload: { type: 'session/queue', sessionId: id, items: queueItems(current.values.inbox, ctx) } };
+    }
+  }
+}
+
+module.exports = { muxFrames };

package/lib/mobile/host-bridge/shims.js

@@ -0,0 +1,218 @@
+'use strict';
+/** 没有 1:1 端点、需要跨端点合成或翻译的几处（翻页游标、模型目录、跟随流、投影基线）。 */
+
+const { invoke, invokeEnvelope, ok, fail, pick, warn, deadline, openStream, SYNTHETIC_DEADLINE_MS } = require('./transport.js');
+
+// ── bespoke：没有 1:1 端点、需要合成或翻译的几处 ──────────────────────────
+
+/**
+ * `session.history` → `session/page`。
+ *
+ * 宿主的 page 请求体多了个必填的 throughSeq（“读到哪一条为止”），没有默认值，必须
+ * 先知道会话当前游标 —— follow 流首帧的 snapshot.cursor 就是它。所以这里开一条
+ * follow 拿游标（读完首帧立刻 break，网关会取消这条流），再翻一页历史。
+ * 返回值把 records 拆回旧形状的 events（history-derive.js 只认 events/hasMore）。
+ */
+async function historyViaPage(ctx, payload, signal) {
+  const sessionId = payload && payload.sessionId;
+  if (typeof sessionId !== 'string' || !sessionId) return fail({ code: 'bad-request', message: '缺少 sessionId' }, 'bad-request');
+  let throughSeq = -1;
+  try {
+    const frames = await openStream(ctx, 'session', 'follow', {
+      request: { address: { kind: 'session', sessionId }, maxMessages: 1 },
+    }, deadline(signal, SYNTHETIC_DEADLINE_MS));
+    for await (const frame of frames) {
+      if (frame && frame.type === 'snapshot' && Number.isSafeInteger(frame.cursor)) {
+        throughSeq = frame.cursor;
+        break;
+      }
+    }
+  } catch (error) {
+    return fail(error);
+  }
+  const request = {
+    address: { kind: 'session', sessionId },
+    throughSeq,
+    ...pick(payload, ['maxMessages', 'beforeSeq', 'turnWindow']),
+  };
+  const result = await invoke(ctx, 'session', 'page', { request }, signal);
+  if (result.error) return fail(result.error);
+  const page = result.value && typeof result.value === 'object' ? result.value : {};
+  const records = Array.isArray(page.records) ? page.records : [];
+  return ok({
+    events: records.map((record) => (record && record.type === 'event' ? record.event : record)).filter(Boolean),
+    hasMore: page.hasMore === true,
+    cursor: throughSeq,
+  });
+}
+
+/**
+ * `session.models` → `session.modelCatalog`。
+ *
+ * 宿主改成全局目录了（args 为空），字段也换了名：default → current、
+ * routableProviders 变成「能不能用这个 provider」。移动端要的 groups 结构两边一致，
+ * 原样带过去即可。
+ */
+async function modelCatalog(ctx, signal) {
+  const result = await invoke(ctx, 'session', 'modelCatalog', {}, signal);
+  if (result.error) return fail(result.error);
+  const catalog = result.value && typeof result.value === 'object' ? result.value : {};
+  const current = catalog.default && typeof catalog.default === 'object'
+    ? pick(catalog.default, ['provider', 'model', 'reasoningEffort'])
+    : null;
+  const routable = Array.isArray(catalog.routableProviders) ? catalog.routableProviders : [];
+  return ok({
+    ...(current ? { current } : {}),
+    routable: Boolean(current && routable.includes(current.provider)),
+    groups: Array.isArray(catalog.groups) ? catalog.groups : [],
+  });
+}
+
+/**
+ * `workspace.list` → `workspace.follow` 的首帧 baseline。
+ *
+ * 0.2.0 的 workspace 只有 follow（流），没有一次性 list；但它的 baseline 值恰好就是
+ * 旧 list 的返回体（items + archivedSessionIds + pinnedSessionIds），所以取首帧即可。
+ */
+async function workspaceListViaFollow(ctx, signal) {
+  try {
+    const frames = await openStream(ctx, 'workspace', 'follow', {}, deadline(signal, SYNTHETIC_DEADLINE_MS));
+    for await (const frame of frames) {
+      if (frame && frame.type === 'baseline' && frame.value) return ok(frame.value);
+    }
+  } catch (error) {
+    return fail(error);
+  }
+  // 流「正常结束却没吐 baseline」不是「你没有工作区」，而是没取到。原先这里返回
+  // ok({ items: [] })，与真成功在下游完全无法区分：宿主正在初始化 / 正忙 / 网关给了
+  // 空流时都会走到这里，于是 { ok: true, items: [] } 一路畅通地通过 lib/index.js 的
+  // 镜像守卫、被当作权威清单推给中转，手机侧表现为工作区整行消失、会话全塌进
+  // 「未分组」，且中转只会附一个 App 根本不看的 stale 标记，不会有任何报错。
+  // 拿不到就是拿不到，如实走错误通道，让调用方去重试或保留上一次结果。
+  warn(
+    ctx,
+    'workspace.follow 流结束前没有给出 baseline 帧，无法确定工作区清单（宿主可能仍在初始化或正忙），' +
+      '本次按失败处理而不是谎报空列表',
+  );
+  return fail({
+    code: 'host-workspace-baseline-missing',
+    message: 'workspace.follow 流结束前没有给出 baseline 帧，无法确定工作区列表',
+  }, 'host-call-failed');
+}
+
+/** 会话摘要内联投影 `session.list items[].projections.values`（没有就是空对象）。 */
+function projectionValues(item) {
+  const projections = item && typeof item === 'object' ? item.projections : null;
+  const values = projections && typeof projections === 'object' ? projections.values : null;
+  return values && typeof values === 'object' ? values : {};
+}
+
+/**
+ * 子代理目录的投影基线预算，比通用合成流（SYNTHETIC_DEADLINE_MS）更紧。
+ *
+ * 手机端一次请求的总预算只有 8 秒（app/src/api.ts 的 REQUEST_TIMEOUT_MS），走中转还要
+ * 多一个 RTT。基线开不出来并不致命 —— session.list 摘要内联的是同一份 values，退回它
+ * 就行，所以宁可慢的时候少等几秒，也别把整次 subagents.list 拖成客户端超时。
+ */
+const SUBAGENT_BASELINE_DEADLINE_MS = 3000;
+
+/**
+ * 开一条 session.control 只读它的首帧 baseline，取回全设备投影快照
+ * `{ [sessionId]: values }`，读完立刻 break（网关随之取消这条流），
+ * 与 workspaceListViaFollow 同一手法。
+ *
+ * 开不成流不算致命：调用方还能退回 session.list 摘要内联的投影，所以这里吞掉异常返回
+ * 空表，而不是把整次调用判失败。
+ */
+async function projectionBaseline(ctx, signal) {
+  // 这里只读首帧 baseline，读完就 break，所以不需要 event-synthesis.js 那份逐帧累积器
+  // （依赖方向也不允许 shims 反过来 require 它），直接取首帧的 projections 即可。
+  let projections = null;
+  try {
+    const frames = await openStream(ctx, 'session', 'control', {}, deadline(signal, SUBAGENT_BASELINE_DEADLINE_MS));
+    for await (const frame of frames) {
+      if (frame && frame.type === 'baseline') {
+        projections = frame.value && typeof frame.value === 'object' ? frame.value.projections : null;
+        break;
+      }
+    }
+  } catch (error) {
+    warn(ctx, `子代理目录：session/control 基线不可用（${error && error.message ? error.message : String(error)}），改用会话列表内联投影`);
+  }
+  const out = new Map();
+  if (projections && typeof projections === 'object') {
+    for (const [sessionId, entry] of Object.entries(projections)) {
+      out.set(sessionId, entry && entry.values && typeof entry.values === 'object' ? entry.values : {});
+    }
+  }
+  return out;
+}
+
+/**
+ * `subagents.list` → `session.control` 投影基线 + `session.list`。
+ *
+ * 0.2.0 撤掉了 subagent.list 这个 RPC，但目录数据一条没少：它变成了会话投影里的
+ * `subagentCatalog` 键，桌面端 @deepseek-ai/dsh-client-ui-subagent 的 CatalogDropdown
+ * 就是读 `state.projectionsBySession` 渲染的。投影基线一次给出**全部**会话的 values，
+ * 父子两层的目录在同一帧里 —— hasChildren 因此不需要按子会话再发 N 次投影查询。
+ *
+ * 投影里没有的是运行时状态：跑没在跑、父会话在不在线。桌面端也是拿 sessions.list 的
+ * summaries 合成 activity 的，这里同口径再取一次会话列表，两边判定完全一致。
+ */
+async function subagentCatalog(ctx, payload, signal) {
+  const parentSessionId = payload && payload.parentSessionId;
+  if (typeof parentSessionId !== 'string' || !parentSessionId) {
+    return fail({ code: 'bad-request', message: '缺少 parentSessionId' });
+  }
+  const list = await invoke(ctx, 'session', 'list', { _request: {} }, signal);
+  if (list.error) return fail(list.error);
+  const items = list.value && Array.isArray(list.value.items) ? list.value.items : [];
+  const byId = new Map();
+  for (const item of items) {
+    if (item && typeof item.sessionId === 'string' && item.sessionId) byId.set(item.sessionId, item);
+  }
+  // 桌面端 ClientSessions.agentAvailable() 的口径：在会话列表里找父会话，读它的
+  // agentAvailable；列表已就绪还找不到就是 false（它那个 undefined 是「列表还没读完」，
+  // 这里 list 是刚 await 回来的，早就就绪了）。
+  //
+  // 这一条是整套里唯一没法离线证实的口径，所以留一级退路：宿主万一不填
+  // agentAvailable（schema 里有，但没实证它一定被赋值），就退成「父会话还在列表里 =
+  // 还在这台宿主上」。宁可偶尔多给一个输入框，也不要整片目录一律只读 —— 后者用户
+  // 点进去发现子代理明明能续话却打不了字，比误判严重得多。
+  const parent = byId.get(parentSessionId);
+  const parentAvailable = !parent
+    ? false
+    : typeof parent.agentAvailable === 'boolean' ? parent.agentAvailable : true;
+
+  const baseline = await projectionBaseline(ctx, signal);
+  // 基线优先：它是桌面端渲染目录的同一份数据。基线里没有这个会话、或者它的
+  // subagentCatalog 还没算出来，就退回列表摘要内联的那份投影；两处都没有就当
+  // 它没有派出过子代理。
+  const catalogOf = (sessionId) => {
+    const fromBaseline = baseline.get(sessionId);
+    if (fromBaseline && Array.isArray(fromBaseline.subagentCatalog)) return fromBaseline.subagentCatalog;
+    const inline = projectionValues(byId.get(sessionId));
+    return Array.isArray(inline.subagentCatalog) ? inline.subagentCatalog : [];
+  };
+
+  const entries = [];
+  for (const item of catalogOf(parentSessionId)) {
+    if (!item || typeof item.id !== 'string' || !item.id) continue;
+    if (item.mode !== 'one-shot' && item.mode !== 'continuable' && item.mode !== 'unknown') continue;
+    const child = byId.get(item.id);
+    entries.push({
+      kind: 'child',
+      id: item.id,
+      mode: item.mode,
+      activity: child && child.running === true ? 'running' : 'inactive',
+      // 子会话不在列表里（已归档/已删）时保守报 false：手机端契约只有布尔值，
+      // 桌面端 isKnownLeaf 那种「目录未加载先留个展开箭头」的三态没法表达，
+      // 而且假箭头点开是空面板，比不显示更糟。
+      hasChildren: catalogOf(item.id).length > 0,
+      ...(typeof item.label === 'string' && item.label ? { label: item.label } : {}),
+    });
+  }
+  return ok({ entries, parentAvailable });
+}
+
+module.exports = { historyViaPage, modelCatalog, workspaceListViaFollow, projectionBaseline, subagentCatalog };