dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/session-send.js

@@ -0,0 +1,278 @@
+'use strict';
+
+/**
+ * 发消息、slash 命令、会话的读/停/改名/分叉。
+ *
+ * promptOnce 的幂等窗口是这里唯一非平凡的逻辑：手机端发消息时网络重试与用户连点
+ * 会产生同一个 clientMessageId 的多次请求，60 秒内它们共享同一个 prompt，而不是
+ * 让模型跑两遍。**只缓存成功**：失败必须能被重试，不能把一次瞬时错误固化成 60 秒的
+ * 静默无响应。
+ *
+ * 文本块恰好一个且以 / 开头时派发为 slash 命令（commands.execute，不发给模型）；
+ * 未知命令或网关未组合时回退普通消息，与桌面 miss 落入默认 sink 的行为一致。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unwrap } = require('./envelope.js');
+const { callSessions, mobilePromptRpcId } = require('./rpc.js');
+const {
+  canonicalDeviceKey, invalidateSessionList, invalidateSessionModels,
+  completionStateOf, sendIdempotencyStateOf,
+} = require('./session-cache.js');
+const { promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive.js');
+const { withIdempotency, requestIdOf } = require('./idempotency.js');
+const readReceipt = require('../read-receipt.cjs');
+
+const SEND_MAX_BODY = 8 * 1024 * 1024; // /send 请求体上限（图片 base64）
+
+/** 仅当 content 恰好为一个文本块时返回其文本，否则 null（带图片/多块不回退命令路径）。 */
+function singleTextOf(content) {
+  if (!Array.isArray(content) || content.length !== 1) return null;
+  const block = content[0];
+  if (!block || block.type !== 'text' || typeof block.text !== 'string') return null;
+  return block.text;
+}
+
+/**
+ * 经宿主 typertGateway 执行 slash 命令（commands.execute——桌面 Web 端同一条派发路径：
+ * 命令注册表命中才执行，绝不经 session.prompt 发给模型；agent 由 agentId 经同一
+ * agent 查找器解析，与 session.prompt 的 turnAgentFor 同源，支持冷会话自动 resume）。
+ *
+ * ⚠️ args 的键名必须**恰好**是宿主 descriptor 的 wire 名（typertGateway 的
+ * assertExactArguments 只认这组名字，多一个少一个都是 gateway/arguments-invalid）。
+ * descriptor：`@deepseek-ai/dsh-commands#commands/execute`，scope wire = agentId，
+ * 参数 = line + submittedAttachments（encoded images 与 staged file receipts，
+ * 按提交顺序排列，纯命令调用传空数组即可）。
+ * 这里曾经写成 `images: []`——少了 submittedAttachments 又多了 images，导致
+ * /permission、/plan 等**所有** slash 命令 400；形状守卫见
+ * test/commands-execute-shape.test.cjs（改这里必须同步那张表）。
+ *
+ * @returns {execution} 派发成功（CommandExecution|undefined，undefined=未知命令/语法不符）
+ *   | {error} 查找或派发失败 | {missing} 网关服务未组合（调用方回退普通消息）
+ */
+async function executeCommand(ctx, sessionId, line) {
+  const gateway = ctx.get && ctx.get('typertGateway');
+  if (!gateway) return { missing: true };
+  try {
+    const execution = await gateway.invoke({
+      namespace: 'commands',
+      method: 'execute',
+      args: { agentId: sessionId, line, submittedAttachments: [] },
+    });
+    return { execution };
+  } catch (error) {
+    return { error };
+  }
+}
+
+/**
+ * POST /api/mobile/v1/session/send（token）
+ * 兼容两种格式：
+ *   旧：{sessionId, text}
+ *   新：{sessionId, content:[{type:'text',text} | {type:'image',mediaType,data(base64),name?}], mode?:'queue'|'steer'}
+ * 恰为单个文本块且以 / 开头时派发为 slash 命令（commands.execute，不发给模型）；
+ * 其余原样透传给 harness 的 session.prompt（图片块需模型支持，不支持时错误原样返回）。
+ */
+function promptOnce(ctx, clientMessageId, payload) {
+  const rpcId = mobilePromptRpcId(clientMessageId);
+  if (!clientMessageId) return callSessions(ctx, 'prompt', payload, rpcId);
+  const state = sendIdempotencyStateOf(ctx);
+  const key = `${payload.sessionId}:${clientMessageId}`;
+  const now = Date.now();
+  const existing = state.get(key);
+  if (existing && now - existing.createdAt < 60_000) return existing.promise;
+  if (existing) state.delete(key);
+
+  const promise = Promise.resolve(callSessions(ctx, 'prompt', payload, rpcId));
+  // Keep the short-lived record so an in-flight/concurrent send with the same
+  // clientMessageId shares one prompt. Only cache a SUCCESS: a rejection must
+  // not poison later retries (a transient error should be retryable), so the
+  // record is released on failure.
+  const record = { createdAt: now, promise };
+  state.set(key, record);
+  promise.then(
+    () => { /* resolved stays cached until the 60s window expires */ },
+    () => { if (state.get(key) === record) state.delete(key); },
+  );
+  return promise;
+}
+
+async function handleSend(ctx, req, res) {
+  const body = await readJsonBody(req, SEND_MAX_BODY);
+  if (!body || typeof body.sessionId !== 'string' || !body.sessionId) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, content | text }' } });
+  }
+  const mode = body.mode === undefined ? 'queue' : body.mode;
+  if (mode !== 'queue' && mode !== 'steer') {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: "mode 必须为 'queue' 或 'steer'" } });
+  }
+  let content;
+  if (Array.isArray(body.content)) {
+    content = body.content;
+  } else if (typeof body.text === 'string' && body.text.trim()) {
+    content = [{ type: 'text', text: body.text }];
+  } else {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 content 数组或 text' } });
+  }
+  if (content.length === 0) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'content 不能为空' } });
+  }
+  const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);
+  for (const block of content) {
+    if (!block || typeof block.type !== 'string') {
+      return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'content 块缺少 type' } });
+    }
+    if (block.type === 'text') {
+      if (typeof block.text !== 'string' || !block.text.trim()) {
+        return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'text 块内容为空' } });
+      }
+    } else if (block.type === 'image') {
+      if (!IMAGE_TYPES.has(block.mediaType) || typeof block.data !== 'string' || !block.data) {
+        return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'image 块需合法 mediaType 与 base64 data' } });
+      }
+    } else {
+      return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: `不支持的 content 块类型: ${block.type}` } });
+    }
+  }
+  // ── Slash 命令派发 ─────────────────────────────────────────────
+  // 已知命令：注册表执行（command/run + command/done 随事件流回传），响应标注 handledAs 供
+  // 客户端跳过「乐观 pending 气泡 + running 态」；未知命令/语法不符（execute 返回 undefined）
+  // 与网关未组合时回退普通消息（对齐桌面 miss 落入默认 sink，`/foo` 仍按文本发送）。
+  const singleText = singleTextOf(content);
+  if (singleText !== null && singleText.trim().startsWith('/')) {
+    const outcome = await executeCommand(ctx, body.sessionId, singleText.trim());
+    if (outcome.error) {
+      const failure = outcome.error.failure
+        || { code: 'command-error', message: outcome.error.message || String(outcome.error), details: {} };
+      return sendJson(res, 400, { ok: false, error: failure });
+    }
+    if (outcome.execution !== undefined) {
+      return sendJson(res, 200, { ok: true, accepted: true, handledAs: 'command' });
+    }
+  }
+  let promptResponse;
+  try {
+    promptResponse = await promptOnce(ctx, typeof body.clientMessageId === 'string' ? body.clientMessageId : '', {
+      sessionId: body.sessionId,
+      mode,
+      content,
+    });
+  } catch (error) {
+    const normalized = promptErrorObject(error);
+    if (normalized.code === MODEL_UNAVAILABLE_ERROR.code) invalidateSessionModels(ctx, req, body.sessionId);
+    return sendJson(res, 400, { ok: false, error: normalized });
+  }
+  const { error } = unwrap(promptResponse);
+  if (error) {
+    const normalized = promptErrorObject(error);
+    if (normalized.code === MODEL_UNAVAILABLE_ERROR.code) invalidateSessionModels(ctx, req, body.sessionId);
+    return sendJson(res, 400, { ok: false, error: normalized });
+  }
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+/** GET /api/mobile/v1/commands?sessionId=…（token）：会话有效命令目录（与桌面 Web 端命令面板
+ * 同源——typertGateway commands.list，即服务端命令注册表对该 agent 生效的完整清单）。
+ * 响应：{ ok, items:[{name, description, input?:{hint}}] }；网关未组合或失败时降级为空清单，
+ * 客户端菜单据此只展示真实可执行的命令（不再硬编码）。 */
+async function handleCommands(ctx, req, res) {
+  const sessionId = new URL(req.url, 'http://x').searchParams.get('sessionId');
+  if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  const gateway = ctx.get && ctx.get('typertGateway');
+  if (!gateway) return sendJson(res, 200, { ok: true, items: [] });
+  try {
+    const descriptors = await gateway.invoke({
+      namespace: 'commands',
+      method: 'list',
+      args: { agentId: sessionId },
+    });
+    const items = Array.isArray(descriptors)
+      ? descriptors
+          .filter((d) => d && typeof d.name === 'string' && d.name && typeof d.description === 'string')
+          .map((d) => ({
+            name: d.name,
+            description: d.description,
+            ...(d.input && typeof d.input === 'object' && typeof d.input.hint === 'string' && d.input.hint
+              ? { input: { hint: d.input.hint } }
+              : {}),
+          }))
+      : [];
+    sendJson(res, 200, { ok: true, items });
+  } catch (error) {
+    // 目录拉取失败不阻塞输入区：降级为空清单（等价桌面网关缺失）。
+    sendJson(res, 200, { ok: true, items: [] });
+  }
+}
+
+/** POST /api/mobile/v1/session/read（token）{sessionId}：清除完成提醒。 */
+async function handleSessionRead(ctx, req, res, fallbackDeviceKey = 'legacy') {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.sessionId !== 'string' || !body.sessionId) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId }' } });
+  }
+  const deviceKey = canonicalDeviceKey(req, fallbackDeviceKey);
+  completionStateOf(ctx, deviceKey).delete(body.sessionId);
+  // Invalidate the cache and any build already reading history. Its generation
+  // check prevents a stale build from restoring `completed` after this ack.
+  invalidateSessionList(ctx, deviceKey);
+  // 桌面端的未读绿点不在宿主里（它在浏览器渲染进程的内存里），这里只记一条水位，
+  // 由插件的客户端半边拉走、在桌面页面里就地清掉。写盘失败不该让「已读」这个动作失败。
+  try {
+    readReceipt.recordRead(body.sessionId);
+  } catch {
+    // 回执台账只是尽力而为的旁路，读不到/写不动都不影响本次已读本身。
+  }
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+/** POST /api/mobile/v1/session/stop（token）{sessionId} */
+async function handleStop(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.sessionId !== 'string') {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId }' } });
+  }
+  const { error } = unwrap(await callSessions(ctx, 'cancel', { sessionId: body.sessionId }));
+  if (error) return sendJson(res, 400, { ok: false, error });
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+/** POST /api/mobile/v1/session/rename（token）{sessionId, title} */
+async function handleRename(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.sessionId !== 'string' || typeof body.title !== 'string' || !body.title.trim()) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, title }' } });
+  }
+  // 改名结果本身是收敛的（同标题重放得到同一状态），但仍然按 requestId 重放：
+  // 重投不该再打一次宿主 RPC，也不该让 App 多等一次往返。
+  const outcome = await withIdempotency(ctx, canonicalDeviceKey(req), requestIdOf(req, body), async () => {
+    const { value, error } = unwrap(await callSessions(ctx, 'rename', { sessionId: body.sessionId, title: body.title }));
+    if (error) return { status: 400, body: { ok: false, error } };
+    // 改完名字立刻丢掉列表缓存：App 保存后会马上 load(true)，那一次拉到的如果还是
+    // 10 秒窗口内的旧行，用户看到的就是「保存了但侧栏没变」。
+    invalidateSessionList(ctx);
+    return { status: 200, body: { ok: true, ...value } };
+  });
+  sendJson(res, outcome.status, outcome.body);
+}
+
+/** POST /api/mobile/v1/session/fork（token）{sessionId} → {ok, sessionId(新)} */
+async function handleFork(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.sessionId !== 'string' || !body.sessionId
+    || (body.atSeq !== undefined && (!Number.isSafeInteger(body.atSeq) || body.atSeq < 0))) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, atSeq? }' } });
+  }
+  const payload = { sessionId: body.sessionId,
+    ...(body.atSeq === undefined ? {} : { atSeq: body.atSeq, increaseTitle: body.increaseTitle !== false }) };
+  // 分叉是**非幂等**写：重投一次就多一个子会话。带 requestId 时重投拿回同一次分叉的 id。
+  const outcome = await withIdempotency(ctx, canonicalDeviceKey(req), requestIdOf(req, body), async () => {
+    const { value, error } = unwrap(await callSessions(ctx, 'fork', payload));
+    if (error) return { status: 400, body: { ok: false, error } };
+    // 新分叉出来的会话要立刻出现在列表里。
+    invalidateSessionList(ctx);
+    return { status: 200, body: { ok: true, ...value } };
+  });
+  sendJson(res, outcome.status, outcome.body);
+}
+
+module.exports = { singleTextOf, executeCommand, promptOnce, handleSend, handleCommands, handleSessionRead, handleStop, handleRename, handleFork };

package/lib/mobile/session-snapshot.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * 消息与统计快照：镜像推送与 /messages 分页共用的两条折叠路径。
+ *
+ * buildMessagesSnapshot（不解析 query）与 handleMessages（解析 beforeSeq/afterSeq/limit）
+ * 是同一套折叠逻辑的两种调用方式，放在一起是为了让「增量水位」的算法改动只发生在
+ * 一处——它们此前隔着一百多行，两边各写一遍归一化，迟早会漂移。
+ *
+ * 上游 session.history 不认 afterSeq（只认 beforeSeq/maxMessages），所以增量轮询在
+ * 插件内用较大的窗口（Math.max(limit, 200)）拉最近若干事件后再按 seq 过滤；缺口
+ * 超过窗口时会漏，此时用 resyncRequired 让客户端回落到权威快照，而不是安静地少消息。
+ */
+
+const { sendJson } = require('../shared/http-util');
+const { unwrap } = require('./envelope.js');
+const { callSessions } = require('./rpc.js');
+const { deriveMessages } = require('./history-derive.js');
+const { resolveEventAttachments } = require('./attachments.js');
+const { createTextImageBudget } = require('./local-images.js');
+
+const MESSAGES_DEFAULT_LIMIT = 50;  // /messages 默认条数
+
+/** 从 history 事件条目取事件序号（entry.event.seq，兼容裸事件 entry.seq）。 */
+function eventSeqOf(entry) {
+  if (!entry) return undefined;
+  return entry.event && entry.event.seq !== undefined ? entry.event.seq : entry.seq;
+}
+
+/**
+ * 镜像快照用的消息折叠（不解析 query，无 afterSeq/beforeSeq/limit 分页）：
+ * 与 handleMessages 的核心折叠逻辑保持一致，供 pushMirror 为活跃会话生成消息快照。
+ */
+async function buildMessagesSnapshot(ctx, sessionId, limit = MESSAGES_DEFAULT_LIMIT) {
+  const { value, error } = unwrap(await callSessions(ctx, 'history', { sessionId, maxMessages: limit }));
+  if (error) return { ok: false, error };
+  const events = (value && value.events) || [];
+  const budget = createTextImageBudget();
+  const resolvedEvents = await Promise.all(events.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget }).then((event) => entry.event ? { ...entry, event } : event)));
+  const messages = deriveMessages(resolvedEvents);
+  const lastSeq = events.length ? (eventSeqOf(events[events.length - 1]) ?? 0) : 0;
+  const hasMore = !!(value && value.hasMore);
+  return { ok: true, items: messages, lastSeq, hasMore };
+}
+
+/**
+ * 镜像快照用的统计投影（与 handleStats 尾部投影读取保持一致）：取整帧 projections，
+ * 并把 plan 归一化为 planMode，供 pushMirror 为活跃会话生成统计快照。
+ */
+async function buildStatsSnapshot(ctx, sessionId) {
+  return statsProjections(ctx, sessionId);
+}
+
+/**
+ * 统计投影快照（handleStats 与 buildStatsSnapshot 共用）。
+ *
+ * 0.2.0 把整帧投影从 session.history/page 的返回值里拆走了（page 只回
+ * events/hasMore/cursor），所以「拉 1 条历史顺带取投影」这条路已经断了；改走
+ * host-bridge 翻译出来的 `apiProxy.sessions.projections({ request: { sessionId } })`，
+ * 返回值是 `{ asOfSeq, values }`。顺带把 plan 归一化成 planMode（plan.active 加可选的
+ * pending），排队条与计划条读的是 planMode。历史轮询是每 5 秒一次的热路径，多背一次
+ * 投影 RPC 划不来，所以宁可让统计单独走投影端点。
+ */
+async function statsProjections(ctx, sessionId) {
+  // 显式给 signal：宿主部分方法内部直接读 signal.aborted，不做 undefined 兜底。
+  const controller = new AbortController();
+  let value;
+  let error;
+  try {
+    ({ value, error } = unwrap(await callSessions(ctx, 'projections', { sessionId }, 'mobile', controller.signal)));
+  } catch (thrown) {
+    // 投影读不出来不该变成一个从路由层逃出去的 rejection：handleStats 要回 400，
+    // pushMirror 那边更是一条都不能抛（抛了整帧快照就丢了）。收敛成正常错误态。
+    error = thrown && typeof thrown === 'object' && typeof thrown.code === 'string'
+      ? { code: thrown.code, message: typeof thrown.message === 'string' ? thrown.message : '读会话投影失败' }
+      : { code: 'host-call-failed', message: thrown && thrown.message ? String(thrown.message) : '读会话投影失败' };
+  }
+  if (error) return { ok: false, error };
+  const projections = value && value.values && typeof value.values === 'object' ? value.values : {};
+  const plan = projections.plan;
+  return {
+    ok: true,
+    projections: plan && typeof plan === 'object' && typeof plan.active === 'boolean'
+      ? { ...projections, planMode: { active: plan.active, ...(typeof plan.pending === 'boolean' ? { pending: plan.pending } : {}) } }
+      : projections,
+  };
+}
+
+/** GET /api/mobile/v1/session/messages?sessionId=…&beforeSeq=…&afterSeq=…&limit=…（token） */
+async function handleMessages(ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const sessionId = url.searchParams.get('sessionId');
+  if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  const beforeSeqRaw = url.searchParams.get('beforeSeq');
+  const beforeSeq = beforeSeqRaw !== null && /^\d+$/.test(beforeSeqRaw) && Number.isSafeInteger(Number(beforeSeqRaw))
+    ? Number(beforeSeqRaw) : null;
+  const requestedLimit = Number(url.searchParams.get('limit'));
+  const limit = Number.isSafeInteger(requestedLimit) && requestedLimit > 0
+    ? Math.min(requestedLimit, 200) : MESSAGES_DEFAULT_LIMIT;
+  // 增量轮询水位：仅当为安全非负整数时使用（空/负数/小数/超界字符串一律忽略，退化为全量或历史分页）。
+  const afterSeqRaw = url.searchParams.get('afterSeq');
+  let afterSeq = null;
+  if (afterSeqRaw !== null && afterSeqRaw !== '' && /^\d+$/.test(afterSeqRaw)) {
+    const parsed = Number(afterSeqRaw);
+    if (Number.isSafeInteger(parsed)) afterSeq = parsed;
+  }
+  const payload = { sessionId, maxMessages: limit };
+  if (beforeSeq !== null) payload.beforeSeq = beforeSeq;
+  // 上游 session.history 不支持 afterSeq（只认 beforeSeq/maxMessages），故在插件内
+  // 用较大的窗口（Math.max(limit, 200)）拉最近若干事件后再过滤 seq > afterSeq，覆盖常见轮询缺口；
+  // 若缺口超过窗口才会漏（简单且安全的折中，不动上游分页协议）。
+  if (afterSeq !== null) payload.maxMessages = Math.max(limit, 200);
+  const { value, error } = unwrap(await callSessions(ctx, 'history', payload));
+  if (error) return sendJson(res, 400, { ok: false, error });
+  const events = (value && value.events) || [];
+  // 增量：只保留水位之后的事件；非 afterSeq 调用时 events 原样保留（行为与之前完全一致）。
+  const filtered = afterSeq !== null ? events.filter((entry) => (eventSeqOf(entry) ?? -1) > afterSeq) : events;
+  // 一页历史共用一个内联图片预算：正文里的本机图片越多，越靠后的那些保持字面 markdown，
+  // 而不是让单次响应无限膨胀（见 local-images.js 的三级预算）。
+  const budget = createTextImageBudget();
+  const resolvedEvents = await Promise.all(filtered.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget }).then((event) => entry.event ? { ...entry, event } : event)));
+  const messages = deriveMessages(resolvedEvents);
+  const hasMore = !!(value && value.hasMore);
+  const seqs = events.map(eventSeqOf).filter((seq) => Number.isSafeInteger(seq) && seq >= 0);
+  const oldestSeq = seqs.length ? Math.min(...seqs) : null;
+  // A truncated history window is not a complete incremental answer. Keep the
+  // cursor unchanged and tell capable clients to resync from an authoritative snapshot.
+  const resyncRequired = afterSeq !== null && hasMore && oldestSeq !== null && oldestSeq > afterSeq;
+  const lastSeq = afterSeq !== null
+    ? (resyncRequired ? afterSeq : (seqs.length ? Math.max(...seqs.filter((seq) => seq > afterSeq), afterSeq) : afterSeq))
+    : (seqs.length ? Math.max(...seqs) : 0);
+  sendJson(res, 200, {
+    ok: true,
+    items: messages,
+    hasMore,
+    lastSeq,
+    ...(oldestSeq !== null ? { oldestSeq } : {}),
+    ...(resyncRequired ? { resyncRequired: true } : {}),
+  });
+}
+
+module.exports = { eventSeqOf, buildMessagesSnapshot, statsProjections, buildStatsSnapshot, handleMessages };