dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/references.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * 移动端「引用发现」API：把桌面端输入框里的 @文件 / @会话 补全补齐到手机上。
+ *
+ * 桌面端由 dsh-client-ui-reference 渲染：输入 @ 后浏览器同时发起
+ * fileReferences/list 与 sessionReferenceResolver/candidates 两个 Remote 调用，
+ * 结果按「文件在前、会话在后」的确定性顺序分组展示；选中文件插入普通 @路径 文本，
+ * 选中会话插入宿主给的规范 mention（@[label](dsh-session:…)）。
+ *
+ * 关键：这两个宿主服务 **不在 apiProxy 上** —— 它们是 Typert Remote 服务
+ * （dsh-file-reference 的 fileReferences、dsh-session-reference 的
+ * sessionReferenceResolver）。手机侧本来就能到它们：dsh-mobile-plugin 与宿主同进程，
+ * lib/mobile/sessions.js 已经用 `ctx.get('typertGateway')` 派发过 commands.execute，
+ * lib/mobile/plugins.js 也走同一条路读 pluginInventory，这里照搬。
+ *
+ * 两条接口（都只是转发宿主的发现域，不做任何排序或截断之外的加工）：
+ *  - GET /api/mobile/v1/file-references?sessionId=…&query=…     → fileReferences.list
+ *  - GET /api/mobile/v1/session-references?sessionId=…&query=…  → sessionReferenceResolver.candidates
+ *
+ * 参数按宿主的 **wire 名** 精确校验：两个方法都是 { agentId, query }，query 是普通
+ * JSON 字符串（与 messageFeedback 的 { request } 包装不同）。
+ *
+ * 语义按宿主原文透传：
+ *  - query 是「@ 或 @" 后面的那段文字」；空串表示列出全部（宿主自己限量）。
+ *  - 文件候选只有 path/kind，目录候选带在路径尾部追加 / 的责任在客户端。
+ *  - 会话候选的 mention 是宿主的规范写法，客户端必须原样发送，不能拿 label 重建。
+ *  - 两个域各自独立降级：任一域不可用不影响另一个域（桌面端也是这个约定）。
+ */
+
+const { sendJson } = require('../shared/http-util');
+
+const REFERENCE_ID_MAX_CHARS = 200;       // sessionId 长度上限
+const REFERENCE_QUERY_MAX_CHARS = 200;    // 查询串长度上限（宿主 schema 只要求 string）
+const REFERENCE_MAX_ITEMS = 50;           // 与宿主 session-reference 的 candidateLimit 默认值一致
+const REFERENCE_KINDS = new Set(['file', 'directory']);
+
+/** 宿主网关；宿主没组合 dsh-api-gateway 时返回 null，调用方回 503。 */
+function gatewayOf(ctx) {
+  return (ctx.get && ctx.get('typertGateway')) || null;
+}
+
+/** 网关缺失/命名空间缺失对客户端是同一件事：宿主这个能力没装。 */
+const UNAVAILABLE = Object.freeze({
+  code: 'reference-unavailable',
+  message: '宿主没有组合引用发现服务（dsh-file-reference / dsh-session-reference / dsh-api-gateway）',
+});
+
+/** 网关自己抛的错（不是业务失败）的文字化。 */
+function errorText(error) {
+  if (!error) return '未知错误';
+  if (typeof error.message === 'string' && error.message) return error.message;
+  return String(error);
+}
+
+/**
+ * 经 typertGateway 调一次引用发现。
+ *
+ * 注意返回值形状：`gateway.invoke()` 返回的是 **decode 后的业务结果本体**
+ * （dsh-api-gateway/lib/index.js:112 `return decode(descriptor.result, result, …)`），
+ * 那层 `{ok:true,value}` 外壳是浏览器传输（connection.rpc.intercept('/api')）加的，
+ * invoke 不负责包。所以形状取决于服务声明的 result schema：
+ *  - messageFeedback 声明的是 ok/error 联合 → invoke 回来就是 {ok:true,value}
+ *  - fileReferences.list 声明的是 z.array(…) → invoke 回来就是一个裸数组
+ * 两个都认，这样宿主以后把 schema 换成联合也不会坏。
+ *
+ * @returns {Promise<{value?: unknown, error?: {code: string, message: string}}>}
+ */
+async function callReference(ctx, namespace, method, agentId, query) {
+  const gateway = gatewayOf(ctx);
+  if (!gateway) return { error: { ...UNAVAILABLE } };
+  let result;
+  try {
+    // 两个方法的声明参数都是 agent(wire=agentId) + query(wire=query)，args 必须精确匹配；
+    // 末位 signal 是可选的取消边界（gateway 会补 NEVER_ABORTED_SIGNAL），这里给真的，
+    // 客户端断开时能让宿主那次发现提前收工。
+    result = await gateway.invoke({
+      namespace,
+      method,
+      args: { agentId, query },
+      signal: new AbortController().signal,
+    });
+  } catch (error) {
+    // 0.2.0 的网关错误码带 `gateway/` 前缀（dsh-api-gateway/src/types.ts:117-136）；
+    // 0.1.x 时期是不带前缀的。两种都认，否则「宿主没装这个服务」的降级分支形同虚设。
+    const raw = error && typeof error.code === 'string' ? error.code.replace(/^gateway\//, '') : ''
+    const code = raw === 'invocation-unavailable' || raw === 'service-unavailable' || raw === 'method-unavailable'
+      ? UNAVAILABLE.code
+      : 'reference-error';
+    return { error: { code, message: errorText(error) } };
+  }
+  // 正常形状：裸数组（宿主声明的 result 就是数组）
+  if (Array.isArray(result)) return { value: result };
+  if (result && typeof result === 'object') {
+    if (result.ok === true) return { value: result.value };
+    if (result.ok === false) {
+      const raw = result.error && typeof result.error === 'object' ? result.error : {};
+      const code = typeof raw.code === 'string' && raw.code ? raw.code : 'reference-error';
+      return { error: { code, message: errorText(raw) } };
+    }
+  }
+  return { error: { code: 'reference-error', message: '宿主引用发现服务返回了意外的结果' } };
+}
+
+/** 文件/目录候选：宿主只承诺 { path, kind }，别的形状一律丢掉。 */
+function normalizeFileCandidate(row) {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) return null;
+  if (typeof row.path !== 'string' || !row.path) return null;
+  if (!REFERENCE_KINDS.has(row.kind)) return null;
+  return { path: row.path, kind: row.kind };
+}
+
+/**
+ * 会话候选：mention 是宿主的规范写法（@[label](dsh-session:…)），客户端必须原样发送，
+ * 所以没有 mention 的行等于不可用，直接丢；label 缺失时退回 sessionId。
+ */
+function normalizeSessionCandidate(row) {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) return null;
+  if (typeof row.sessionId !== 'string' || !row.sessionId) return null;
+  if (typeof row.mention !== 'string' || !row.mention) return null;
+  const label = typeof row.label === 'string' && row.label ? row.label : row.sessionId;
+  return {
+    sessionId: row.sessionId,
+    label,
+    mention: row.mention,
+    ...(typeof row.cwd === 'string' && row.cwd ? { cwd: row.cwd } : {}),
+    createdAt: typeof row.createdAt === 'number' ? row.createdAt : 0,
+  };
+}
+
+/** 会话 id 校验：空/超长直接拒绝，不把垃圾转发给宿主。 */
+function normalizeId(value, label) {
+  if (value === null || value === undefined) return { error: `缺少 ${label}` };
+  if (typeof value !== 'string') return { error: `${label} 必须是字符串` };
+  const id = value.trim();
+  if (!id) return { error: `缺少 ${label}` };
+  if (id.length > REFERENCE_ID_MAX_CHARS) return { error: `${label} 过长` };
+  return { id };
+}
+
+/** 查询串：缺失等同空串（列出全部）；只截长度，内容原样交给宿主筛选。 */
+function normalizeQuery(value) {
+  if (value === null || value === undefined) return { query: '' };
+  if (typeof value !== 'string') return { error: 'query 必须是字符串' };
+  if (value.length > REFERENCE_QUERY_MAX_CHARS) return { error: `query 过长（上限 ${REFERENCE_QUERY_MAX_CHARS} 字符）` };
+  return { query: value };
+}
+
+/** 能力缺失是 503，其余都是 400。 */
+function statusOf(error) {
+  if (!error) return 400;
+  if (error.code === UNAVAILABLE.code) return 503;
+  return 400;
+}
+
+/** 两条 GET 路由共用的骨架：校验 → 转发 → 规范化 → 限量。 */
+async function handleReferenceList(ctx, req, res, spec) {
+  const params = new URL(req.url, 'http://x').searchParams;
+  const session = normalizeId(params.get('sessionId'), 'sessionId');
+  if (session.error) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: session.error } });
+  const query = normalizeQuery(params.get('query'));
+  if (query.error) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: query.error } });
+
+  const { value, error } = await callReference(ctx, spec.namespace, spec.method, session.id, query.query);
+  if (error) return sendJson(res, statusOf(error), { ok: false, error });
+
+  const rows = Array.isArray(value) ? value : [];
+  const items = [];
+  for (const row of rows) {
+    const item = spec.normalize(row);
+    if (item) items.push(item);
+    if (items.length >= REFERENCE_MAX_ITEMS) break;
+  }
+  sendJson(res, 200, { ok: true, items });
+}
+
+/** GET /api/mobile/v1/file-references?sessionId=…&query=… → { ok, items:[{path,kind}] }。 */
+function handleFileReferences(ctx, req, res) {
+  return handleReferenceList(ctx, req, res, {
+    namespace: 'fileReferences',
+    method: 'list',
+    normalize: normalizeFileCandidate,
+  });
+}
+
+/**
+ * GET /api/mobile/v1/session-references?sessionId=…&query=… →
+ * { ok, items:[{sessionId,label,mention,cwd?,createdAt}] }。
+ */
+function handleSessionReferences(ctx, req, res) {
+  return handleReferenceList(ctx, req, res, {
+    namespace: 'sessionReferenceResolver',
+    method: 'candidates',
+    normalize: normalizeSessionCandidate,
+  });
+}
+
+module.exports = {
+  handleFileReferences,
+  handleSessionReferences,
+  normalizeFileCandidate,
+  normalizeSessionCandidate,
+  normalizeId,
+  normalizeQuery,
+  statusOf,
+  REFERENCE_QUERY_MAX_CHARS,
+  REFERENCE_MAX_ITEMS,
+  REFERENCE_UNAVAILABLE: UNAVAILABLE,
+};

package/lib/mobile/rpc.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * 调宿主 apiProxy 的两扇门：`sessions.*` 与 `agentPresets.*`。
+ *
+ * 抽出来是因为这两扇门此前各有两份实现——sessions.js 一份、agent-presets.js 一份
+ * callAgentPresets（逐字相同），而 callSessions 是 sessions.js 内部 21 处的公共依赖，
+ * 一旦 sessions.js 被拆分，21 处调用就得跟着搬家。
+ *
+ * 这里收的不只是「转发」：callSessions 还带两件必须跟着转发走的语义。
+ *
+ * 1. signal 必须显式传。宿主 `sessions.<method>(request, signal)` 的第二个参数是
+ *    取消信号，宿主内部 `isAborted(signal)` 直接读 `signal.aborted`、不做
+ *    undefined 兜底：search 这类会查 signal 的方法不传就抛
+ *    `Cannot read properties of undefined (reading 'aborted')`。
+ * 2. list 的在途合流。sessions.list 会扫描所有压缩日志；同一个 Host 可能同时收到
+ *    桌面 completion、移动端列表和通知监控的请求，不合流就是一次刷新被放大成 N 次
+ *    磁盘扫描。**但写后刷新（?fresh=1）不能搭在途 list 的车**：被合流到的那个请求
+ *    发起于写入之前，拿回来的是旧列表，于是「刚改完又显示成改之前」。
+ *
+ * 依赖方向：rpc.js → history-derive（只为 rpcId 前缀常量），是叶子之上的薄层。
+ */
+
+const { MOBILE_PROMPT_RPC_PREFIX } = require('./history-derive.js');
+
+// 移动端提示词的 rpcId 约定与 user 消息回溯共用，前缀常量定义放在没有依赖的
+// history-derive 里（history-derive 要用 clientMessageIdFromSource，而会话模块
+// 又 require 它；反向引用会成环——历史上就是这个函数在 history-derive 里找不到
+// 定义，历史路径一有 user 消息就报 "clientMessageIdFromSource is not defined"）。
+function mobilePromptRpcId(clientMessageId) {
+  return clientMessageId ? `${MOBILE_PROMPT_RPC_PREFIX}${clientMessageId}` : 'mobile';
+}
+
+/**
+ * 调宿主 apiProxy.agentPresets.*（Agent 预设列表 / 选择）。
+ * 注意：宿主 list 声明不接 signal，select 接第二个参数；这里统一不传，避免把
+ * undefined 交给内部会读 signal 的方法。
+ */
+function callAgentPresets(ctx, method, payload) {
+  return ctx.apiProxy.agentPresets[method]({ rpcId: 'mobile', method: `agentPreset.${method}`, payload });
+}
+
+// sessions.list 的在途合流表按 ctx 隔离（不同宿主 / 测试上下文各算各的）。
+const sessionListInFlight = new WeakMap();
+
+function callSessions(ctx, method, payload, rpcId = 'mobile', signal, options) {
+  const invoke = () => ctx.apiProxy.sessions[method]({ rpcId, method: `session.${method}`, payload }, signal);
+  if (method !== 'list') return invoke();
+  if (options && options.fresh) return invoke();
+
+  const existing = sessionListInFlight.get(ctx);
+  if (existing) return existing;
+
+  let request;
+  try {
+    request = Promise.resolve(invoke());
+  } catch (error) {
+    // 同步抛出的也要变成 rejected promise：下面要挂 .then 清理并把它交给调用方，
+    // 否则同步异常会绕过 tracked 的回收，永久把这次合流卡在表里。
+    request = Promise.reject(error);
+  }
+  const tracked = request.then(
+    value => {
+      if (sessionListInFlight.get(ctx) === tracked) sessionListInFlight.delete(ctx);
+      return value;
+    },
+    error => {
+      if (sessionListInFlight.get(ctx) === tracked) sessionListInFlight.delete(ctx);
+      throw error;
+    },
+  );
+  sessionListInFlight.set(ctx, tracked);
+  return tracked;
+}
+
+module.exports = { callSessions, callAgentPresets, mobilePromptRpcId };

package/lib/mobile/session-cache.js

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * 会话侧的按 ctx 隔离状态：十一张表，一个入口。
+ *
+ * 这些表此前全是 sessions.js 的模块级 WeakMap。它们之所以必须按 ctx 隔离，是因为
+ * 它们的值属于**宿主进程状态**（某个会话正在跑、某个列表刚构建完、某条发送已经
+ * 幂等过），不同宿主 / 测试上下文混在一起会互相污染。
+ *
+ * 抽出来是为了让「哪些东西是模块级可变状态」这件事有个明确的名字和位置。此前它们
+ * 和会话 handler 混在一个 1400 行文件里，读代码时得先分清哪行是状态、哪行是逻辑。
+ * 抽完之后形状很干净：**每个访问器都保证返回的是那个表里给 ctx（或 ctx+device）
+ * 建好的那个 Map/状态对象，调用方拿到就能直接用，不需要再判空。**
+ *
+ * 依赖方向：session-cache.js 不依赖任何上层模块，是叶子。
+ */
+
+// Model responses are derived metadata only. They are never populated with credentials
+// or provider secrets, and the key includes the requesting device and session.
+const sessionModelsCache = new WeakMap();
+const MAX_SESSION_MODEL_CACHE_ENTRIES = 256;
+
+const sessionListResponseCache = new WeakMap();
+const mirrorHistoryCache = new WeakMap();
+// Cache only the derived last-message preview. The full history stays outside
+// the cache so repeated mobile list refreshes do not re-read/decompress logs.
+const sessionPreviewCache = new WeakMap();
+const sessionPreviewInFlight = new WeakMap();
+// 上一次真正重读该会话 history 补预览的时间（运行中会话的节流用，见 sessions.js）。
+const sessionPreviewClock = new WeakMap();
+// 完成提醒属于宿主进程状态：按 ctx 隔离，避免不同宿主/测试上下文互相污染。
+const completionStates = new WeakMap();
+const completionGenerations = new WeakMap();
+// Prevent duplicate prompt calls when a mobile request is retried after a timeout.
+const sendIdempotency = new WeakMap();
+// 写操作（新建/改名/归档/分叉）的 requestId 重放表：同一次写在换通道重投后不再执行第二遍。
+// 与 sendIdempotency 分开是因为键与生命周期不同（那边按 sessionId+clientMessageId，60s）。
+const writeIdempotency = new WeakMap();
+
+/** 设备维度：同一个 ctx 下多台手机各自一份，缺省用 'legacy'（未带 x-dsh-device 的调用）。 */
+function canonicalDeviceKey(req, fallback = 'legacy') {
+  const value = req?.headers?.['x-dsh-device'];
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function sessionModelsStateOf(ctx, deviceKey, sessionId) {
+  let state = sessionModelsCache.get(ctx);
+  if (!state) { state = new Map(); sessionModelsCache.set(ctx, state); }
+  const key = `${deviceKey}\0${sessionId}`;
+  let entry = state.get(key);
+  if (!entry) {
+    while (state.size >= MAX_SESSION_MODEL_CACHE_ENTRIES) state.delete(state.keys().next().value);
+    entry = { value: null, fetchedAt: 0, promise: null };
+  } else {
+    // Treat accesses as recent so active sessions survive the bounded eviction.
+    state.delete(key);
+  }
+  state.set(key, entry);
+  return entry;
+}
+
+function invalidateSessionModels(ctx, req, sessionId) {
+  const deviceKey = canonicalDeviceKey(req);
+  const state = sessionModelsCache.get(ctx);
+  state?.delete(`${deviceKey}\0${sessionId}`);
+}
+
+function sessionListResponseState(ctx, deviceKey = 'legacy') {
+  let byDevice = sessionListResponseCache.get(ctx);
+  if (!byDevice) {
+    byDevice = new Map();
+    sessionListResponseCache.set(ctx, byDevice);
+  }
+  let state = byDevice.get(deviceKey);
+  if (!state) {
+    // droppedAt 是这份缓存的「朝代」：dropSessionListCache 每次丢弃内容就 +1，
+    // 于是变更前发起的那次构建落地时能看出自己的数据已经过时（见 handleSessions）。
+    state = { value: null, updatedAt: 0, promise: null, droppedAt: 0 };
+    byDevice.set(deviceKey, state);
+  }
+  return state;
+}
+
+function sessionPreviewStateOf(ctx) {
+  let state = sessionPreviewCache.get(ctx);
+  if (!state) {
+    state = new Map();
+    sessionPreviewCache.set(ctx, state);
+  }
+  return state;
+}
+
+function sessionPreviewInFlightStateOf(ctx) {
+  let state = sessionPreviewInFlight.get(ctx);
+  if (!state) {
+    state = new Map();
+    sessionPreviewInFlight.set(ctx, state);
+  }
+  return state;
+}
+
+/** 运行中会话上一次补预览的时间戳表（按 ctx 隔离，见 sessions.js 的节流）。 */
+function sessionPreviewClockOf(ctx) {
+  let state = sessionPreviewClock.get(ctx);
+  if (!state) {
+    state = new Map();
+    sessionPreviewClock.set(ctx, state);
+  }
+  return state;
+}
+
+/** 镜像用的历史缓存：按 ctx 一张 Map，key 自带 LRU 淘汰。 */
+function mirrorHistoryStateOf(ctx) {
+  let cache = mirrorHistoryCache.get(ctx);
+  if (!cache) { cache = new Map(); mirrorHistoryCache.set(ctx, cache); }
+  return cache;
+}
+
+function completionStateOf(ctx, deviceKey = 'legacy') {
+  let byDevice = completionStates.get(ctx);
+  if (!byDevice) {
+    byDevice = new Map();
+    completionStates.set(ctx, byDevice);
+  }
+  let states = byDevice.get(deviceKey);
+  if (!states) {
+    states = new Map();
+    byDevice.set(deviceKey, states);
+  }
+  return states;
+}
+
+/**
+ * 清掉某个会话在**所有**设备维度上的完成提醒，返回真正清掉的设备数。
+ *
+ * 与 handleSessionRead 里那句 `completionStateOf(ctx, deviceKey).delete(...)` 的区别：
+ * 那个只清「刚点开的那台手机」自己的提醒（每台手机各有一份，互不干扰）；这个用于
+ * **桌面端说「我读过了」**——读一次就是读过了，不该只清某台设备。
+ *
+ * 清掉（而不是标记成已读）是刻意的：重建出来的条目 `wasRunning` 为 false，历史折叠
+ * （completion.js 的 confirmCompletionFromHistory）会因此拒绝确认，于是**之后**完成的
+ * 轮次照样能重新亮起来 —— 「新一轮完成压过更早的已读」这条语义就落在这里。
+ */
+function clearCompletionForAllDevices(ctx, sessionId) {
+  const byDevice = completionStates.get(ctx);
+  if (!byDevice) return 0;
+  let cleared = 0;
+  for (const states of byDevice.values()) {
+    if (states.delete(sessionId)) cleared += 1;
+  }
+  return cleared;
+}
+
+function completionGenerationOf(ctx, deviceKey) {
+  let generations = completionGenerations.get(ctx);
+  if (!generations) {
+    generations = new Map();
+    completionGenerations.set(ctx, generations);
+  }
+  return generations.get(deviceKey) || 0;
+}
+
+function bumpCompletionGeneration(ctx, deviceKey) {
+  const next = completionGenerationOf(ctx, deviceKey) + 1;
+  completionGenerations.get(ctx).set(deviceKey, next);
+  return next;
+}
+
+function sendIdempotencyStateOf(ctx) {
+  let state = sendIdempotency.get(ctx);
+  if (!state) {
+    state = new Map();
+    sendIdempotency.set(ctx, state);
+  }
+  return state;
+}
+
+/** 写操作幂等表（实现在 mobile/idempotency.js，这里只保证按 ctx 隔离）。 */
+function writeIdempotencyStateOf(ctx) {
+  let state = writeIdempotency.get(ctx);
+  if (!state) {
+    state = new Map();
+    writeIdempotency.set(ctx, state);
+  }
+  return state;
+}
+
+/**
+ * 丢弃会话列表缓存（含正在构建的那一次）。
+ *
+ * `/sessions` 的完整响应会缓存 SESSION_LIST_CACHE_MS（10 秒），本意是压住手机轮询对
+ * 桌面的冲击。但凡是**改变列表内容**的动作都必须立刻把它丢掉，否则 App 在自己刚做完
+ * 的动作上看到的是最长 10 秒前的旧数据——真机上「重命名会话」保存后侧栏那一行纹丝不
+ * 动、「归档会话」按下去那一行照旧留着，看着都像没生效（宿主的标题其实早就改了）。
+ *
+ * 只清 `value` 不够：若此刻正有一次构建在飞，它读的是变更前的历史，落地后会把旧数据
+ * 又写回缓存。所以连 `promise` 一起清，并用 completion generation 兜住（与
+ * handleSessionRead 同款守卫，见那里的注释）。
+ *
+ * @param {object} ctx
+ * @param {string} [deviceKey] 只清这一台设备的缓存；缺省清掉该 ctx 下所有设备。
+ */
+function invalidateSessionList(ctx, deviceKey) {
+  const byDevice = sessionListResponseCache.get(ctx);
+  if (!byDevice) return;
+  const keys = deviceKey === undefined ? [...byDevice.keys()] : [deviceKey];
+  for (const key of keys) {
+    const state = byDevice.get(key);
+    if (!state) continue;
+    state.value = null;
+    state.updatedAt = 0;
+    state.promise = null;
+    bumpCompletionGeneration(ctx, key);
+  }
+}
+
+/**
+ * 丢弃会话列表缓存，但**不抬 completion generation**。
+ *
+ * 与 invalidateSessionList 的分工：那个用于「写操作刚发生」，必须连在飞构建与完成态
+ * 一起作废；这个用于「宿主的清单内容变了，我（镜像推送调度器）先看见了」。后者在生成期
+ * 每 500ms 就会发生一次（会话的 updatedAt 一直在动），如果也抬 generation，
+ * buildSessionsResponse 里那句 `completionGenerationOf(...) === generation` 就永远不成立，
+ * `confirmCompletionFromHistory` 再也执行不到 —— 侧栏的 completed / 红点会彻底不亮。
+ *
+ * 所以在飞构建靠状态自带的「朝代」（droppedAt）而不是 generation 来作废：handleSessions
+ * 建构建前记下朝代，落地时发现朝代变了就不把旧内容写回缓存。这样既不需要抬 generation，
+ * 又不会出现「变更前发起的那次构建在变更后落地，把旧列表按新时间戳缓存 10 秒」。
+ *
+ * @param {object} ctx
+ * @param {string} [deviceKey] 只丢这一台设备的缓存；缺省丢掉该 ctx 下所有设备。
+ */
+function dropSessionListCache(ctx, deviceKey) {
+  const byDevice = sessionListResponseCache.get(ctx);
+  if (!byDevice) return;
+  const keys = deviceKey === undefined ? [...byDevice.keys()] : [deviceKey];
+  for (const key of keys) {
+    const state = byDevice.get(key);
+    if (!state) continue;
+    state.value = null;
+    state.updatedAt = 0;
+    state.droppedAt = (state.droppedAt || 0) + 1;
+  }
+}
+
+module.exports = {
+  canonicalDeviceKey,
+  sessionModelsStateOf,
+  invalidateSessionModels,
+  sessionListResponseState,
+  invalidateSessionList,
+  dropSessionListCache,
+  sessionPreviewStateOf,
+  sessionPreviewInFlightStateOf,
+  sessionPreviewClockOf,
+  mirrorHistoryStateOf,
+  completionStateOf,
+  clearCompletionForAllDevices,
+  completionGenerationOf,
+  bumpCompletionGeneration,
+  sendIdempotencyStateOf,
+  writeIdempotencyStateOf,
+};

package/lib/mobile/session-goal.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/** 目标条动作透传：edit / pause / resume / clear。ref 来自 goal 会话投影，宿主以它做 CAS。 */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unwrap } = require('./envelope.js');
+
+/** 调宿主 apiProxy.goals.*（目标条的动作：edit/pause/resume/clear）。 */
+function callGoals(ctx, method, payload) {
+  return ctx.apiProxy.goals[method]({ rpcId: 'mobile', method: `goals.${method}`, payload });
+}
+
+/**
+ * POST /api/mobile/v1/session/goal（token）{ action, ref, objective? }
+ * 目标条动作透传：pause / resume / clear / edit（edit 需 objective）。
+ * ref 来自 goal 会话投影（{id, revision}），宿主以 ref 做 CAS 守卫。
+ */
+async function handleGoalAction(ctx, req, res) {
+  const body = await readJsonBody(req, 64 * 1024);
+  const action = body && typeof body.action === 'string' ? body.action : '';
+  const ref = body && body.ref;
+  const sessionId = body && typeof body.sessionId === 'string' ? body.sessionId : '';
+  if (!action || !sessionId || !ref || typeof ref !== 'object') {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, action, ref }' } });
+  }
+  if (action === 'edit') {
+    const objective = body.objective;
+    if (typeof objective !== 'string' || !objective.trim()) {
+      return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'edit 需要非空 objective' } });
+    }
+    const { value, error } = unwrap(await callGoals(ctx, 'edit', { sessionId, ref, objective: objective.trim() }));
+    if (error) return sendJson(res, 400, { ok: false, error });
+    return sendJson(res, 200, { ok: true, ...(value || {}) });
+  }
+  const allowed = new Set(['pause', 'resume', 'clear']);
+  if (!allowed.has(action)) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: `不支持的目标动作: ${action}` } });
+  }
+  const { value, error } = unwrap(await callGoals(ctx, action, { sessionId, ref }));
+  if (error) return sendJson(res, 400, { ok: false, error });
+  sendJson(res, 200, { ok: true, ...(value || {}) });
+}
+
+module.exports = { callGoals, handleGoalAction };