@coda-console/grok-bot 0.3.0 → 0.3.1

package/README.md

@@ -46,6 +46,8 @@ node /workspace/.coda-bot/coda-bot.mjs mcp <Coda-sessionId>
 
 工具包括 `read_thread`、`read_tool_call`、`agents`、`status`、`workflow_status`、`workflow_list`、`telemetry`、`machines`、`machine_diagnostics`、`new_session`、`send`（MCP 名加 `coda_` 前缀）。Coda 工具调用保留完整输入输出；轮外只读调用仅写日志，不开启空轮次。`new_session` 在目标目录开独立会话，`send` 给已有会话发消息，均由 Coda 授权卡片批准；稳定 requestId、turn 票据和后台 send 结果由适配器处理。
 
+巡检按远端 Skill 先开只归因的独立会话（不改代码、不开 PR），prompt 写清现象、证据、时间和版本，要求结论、证据链、置信度与是否建议修复。下次巡检读取结论，确认需要修复的代码问题才开修复会话，引用归因会话与结论并走完仓库 PR 流程；偶发、外部因素或用户暂不处理的问题只记忆。用户指定的 Agent、暂不处理事项等也写进记忆，开会话前先读取遵守，不在 Skill 固定模型或推理强度。卡片审批、不重复开会话、不轮询等规则照旧；GitHub 只读限制只约束 Bot 自己。
+
 诊断工具需在 Coda 安装并为目录启用内置「机器诊断」插件（`diagnostics` MCP），参见 [诊断工具](https://github.com/coda-console/coda/pull/2003)；遥测端点参见 [遥测 JSON 接口](https://github.com/coda-console/coda/pull/2004)。没有 new_session 的旧 Coda 会如实报不可用。
 
 ## 从 0.1.7 升级
@@ -62,9 +64,11 @@ node /workspace/.coda-bot/coda-bot.mjs mcp <Coda-sessionId>
 
 这是未获稳定性保证的私有接口，上游升级可能使登录、字段或接口失效；错误会显示在会话中。[Cursor 服务条款 §1.5](https://cursor.com/terms-of-service) 限制逆向工程等行为（法律不允许此限制的情况除外），使用前需评估该条款风险。
 
-- SetStatus 只提供名称/说明，映射为 tool_call 标题和状态，不伪造云端工具输入输出。thinking 只显示“正在思考”，不是思考正文。
-- 按 requestId/turnId 归并，成功结束且已有正文时立即核对历史并收尾；没有正文时，等到 serverTimeMs 晚于 settledAtMs 的心跳或 5 秒宽限期，再核对历史并收尾，不把正常的静默运行挂到 turnTimeout。上游没有“最后正文已落盘”标志，极迟消息仍作为补充显示，不静默丢弃。
+- 原生活动标题保留 detail，按 callId/tool/target/detail 识别活动。0.78.1 的 tool/target 是自由字符串；已有只读记录的 43 条 tool 活动均为 SetStatus，它只报告说明，不能据此推断底层命令或文件操作，因此 SetStatus 与未经验证的名称均报 ACP `other`。target 没有已验证的文件路径语义，不编造 locations 或输入输出。thinking 只显示“正在思考”，不是思考正文。
+- Coda 代理工具的 kind：read_thread、read_tool_call、agents、status、workflow_status、workflow_list、machines、machine_diagnostics → `other`（数据查询，显示「调用 N 个工具」；Coda 会把没有路径的 `read` 调用也计为文件，不能用于这些查询）；telemetry → `fetch`（「联网 N 次」）；new_session、send → `other`。保留完整输入输出，没有文件位置就不报 locations。
+- 按 requestId/turnId 归并。成功结算且主 Agent 无运行、撰写、重试、activity 或 awaiting 状态时才考虑收尾；再次出现主 Agent 活动会撤销待收尾状态。最后正文之后没有活动，立即核对历史并收尾；先回复又出现活动则等待后文，最多宽限 10 秒，再核对历史；完全无正文仍用 5 秒宽限。后文到达即可完成，不必等满宽限。hasRunningSubagents 属于独立 Routine 观测，不阻塞主轮次；heartbeat.serverTimeMs 只有时间，没有正文游标，不作为正文交付完成的保证。上游没有“最后正文已落盘”标志，超出宽限或取消/超时后的消息仍原样显示为 Bot 的话，不加前缀，不按正文去重。
+- 10 秒宽限依据：2026-10-31 的 requestId `11223fc4-fbff-4364-a6d7-47911999652b`，只读历史中 t7s0/t7s1 正文时间为 15:34:39.339 / 15:34:51.225（SGT），相差 11.886 秒；Coda 的中间活动在 15:34:43.694 被收尾，t7s1 在 15:34:51.495 到达，晚 7.801 秒。历史不保留该次 settlement，不能把本地收尾时间当精确的原生 settledAtMs；10 秒是覆盖已知约 8 秒延迟的兜底，不是上游保证。正常“工具→最终正文→结算”不增加等待。
 - entryId、updatedSeq 和正文摘要只保留按 updatedSeq 排序的最近 2000 条，每批条目合并写盘；更早条目若被服务端修订，会当作新条目呈现。断线按游标重连，游标失效分页读历史补齐并去重，不重发用户消息。首次选择只建立历史基线，不灌入旧聊天。正文被服务端省略或消息类型不支持时明确提示去 Grok 客户端查看。
 - Stop 调 InterruptGrokBotAgentRun。widget 选项变成 Coda 卡片，选择后交回 RespondGrokBotWidget；未选择则不代答。auto-review 尚未实测，收到 awaiting 时提示去 Grok 客户端处理，并记事件日志。
 
-实机已验证官方登录、Bot 列表、原生发送/状态/活动/回复、Interrupt、widget 选择交回、Routine run 与 executor ID 的关联，以及无需任何 Coda 汇报工具也会出现的主会话结论（结束状态比正文早 121 ms）。完整新适配器尚未真机部署；自动续期、auto-review、executor 内部过程未实测。适配器测试使用假原生服务端与假时钟。
+实机已验证官方登录、Bot 列表、原生发送/状态/活动/回复、Interrupt、widget 选择交回、Routine run 与 executor ID 的关联，以及无需任何 Coda 汇报工具也会出现的主会话结论（结束状态比正文早 121 ms）。完整新适配器尚未真机部署；自动续期、auto-review、executor 内部过程未实测。适配器测试使用假原生服务端与假时钟。0.3.1 仅只读核对原生历史、订阅及已有协议/观察记录，没有向真实 Bot 发消息或运行新版适配器，也没有更新云电脑与 Routine。

package/agent/session.mjs

@@ -14,6 +14,9 @@ const DIAGNOSTICS = new Set(['machines', 'machine_diagnostics']);
 const fail = message => { throw Object.assign(new Error(message), { code: -32602 }); };
 const object = value => value && typeof value === 'object' && !Array.isArray(value);
 export const SETTLEMENT_GRACE_MS = 5000;
+// Observed t7s1 arrived 7.8 s after Coda closed a successful run whose first
+// reply preceded a tool activity. There is no transcript-drained marker.
+export const ACTIVITY_REPLY_GRACE_MS = 10_000;
 export const SUBMISSION_WAIT_MS = 20_000;
 function canonical(value) {
   if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
@@ -86,7 +89,7 @@ export class Adapter {
     turn.timer = this.clock.setTimeout(() => {
       if (s.turn !== turn) return;
       turn.failed = true;
-      this.say(s, `等待 Grok Bot 超过 ${this.settings['grok-bot.turnTimeout'] ?? 'PT30M'}，本轮已结束；云端任务未必停止。之后收到的原生消息将标为补充消息。`);
+      this.say(s, `等待 Grok Bot 超过 ${this.settings['grok-bot.turnTimeout'] ?? 'PT30M'}，本轮已结束；云端任务未必停止。之后收到的原生消息仍会显示。`);
       this.finish(s, 'end_turn');
     }, this.timeout);
     return turn;
@@ -261,14 +264,14 @@ export class Adapter {
       if (!late && s.turn?.autonomous && s.turn.hasReply && s.turn.nativeId && s.turn.nativeId !== body.requestId) this.finish(s, 'end_turn');
       if (!s.turn) {
         this.start(s, true);
-        if (late) { this.say(s, 'Grok 上一轮补充消息：'); s.turn.settlement = { turnId: body.requestId, outcome: 'success', settledAtMs: String(this.now()) }; }
+        if (late) s.turn.settlement = { turnId: body.requestId, outcome: 'success', settledAtMs: String(this.now()) };
       }
       const turn = s.turn;
       if (!turn.nativeId && !(late && turn.messageId)) turn.nativeId = body.requestId;
-      // Preserve late native output as an explicit supplement, never silently drop it.
-      if (body.requestId && turn.nativeId !== body.requestId) this.say(s, 'Grok 上一轮补充消息：');
+      // Late output remains the Bot's own speech, even during another prompt.
       if (turn.nativeId === body.requestId) {
         turn.hasReply = true;
+        turn.awaitingReply = false;
         if (s.lastSettlement?.turnId === body.requestId)
           (turn.pendingSettlements ??= new Map()).set(body.requestId, s.lastSettlement);
       }
@@ -285,30 +288,42 @@ export class Adapter {
       const live = event.live;
       if (live.hasRunningSubagents || s.hadSubagents) void s.routines.hint(!!live.hasRunningSubagents);
       s.hadSubagents = !!live.hasRunningSubagents;
-      if (live.isRunning && !s.turn) this.start(s, true);
-      if (live.isRunning && s.turn) {
+      // Subagents can run independently; heartbeat serverTimeMs is not a
+      // transcript watermark. Only main-agent activity affects this turn.
+      const busy = !!(live.isRunning || live.isComposingMessage || live.isRetrying || live.activity || live.awaiting);
+      if (busy && !s.turn) this.start(s, true);
+      if (busy && s.turn) {
         s.turn.nativeRunning = true;
+        if (s.turn.hasReply) s.turn.awaitingReply = true;
+        delete s.turn.settlement;
+        this.clock.clearTimeout(s.turn.settlementTimer);
+        s.turn.settlementTimer = null;
         if (live.activity?.kind === 'thinking' && !s.turn.thinking) {
           s.turn.thinking = true;
           this.update(s, { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'Grok 正在思考（原生状态，未提供思考正文）' } });
         }
         if (live.activity?.kind === 'tool') {
           const title = live.activity.detail || live.activity.tool || 'Grok 活动';
-          if (title !== s.turn.activityTitle) {
+          const activityKey = JSON.stringify([live.activity.callId, live.activity.tool, live.activity.target, title]);
+          if (activityKey !== s.turn.activityKey) {
             if (s.turn.activityId) this.update(s, { sessionUpdate: 'tool_call_update', toolCallId: s.turn.activityId, status: 'completed' });
-            s.turn.activityTitle = title; s.turn.activityId = randomUUID();
+            s.turn.activityKey = activityKey; s.turn.activityId = randomUUID();
+            // 0.78.1 defines tool/target as free strings. Observed SetStatus
+            // carries a prose summary, not the operation it describes. Keep
+            // it (and unverified names) as other; target is not a file path.
             this.update(s, { sessionUpdate: 'tool_call', toolCallId: s.turn.activityId, title, kind: 'other', status: 'in_progress' });
           }
         }
       }
+      if (!busy && s.turn) s.turn.nativeRunning = false;
       if (live.awaiting) {
         this.log(JSON.stringify({ sessionId: s.id, nativeAwaiting: live.awaiting }));
         if (!s.awaiting) { if (!s.turn) this.start(s, true); this.say(s, 'Grok 正在等待原生审批，请到 Grok 客户端处理。'); }
       }
       s.awaiting = !!live.awaiting;
       const settlement = live.lastTurnSettlement;
-      if (settlement && !live.isRunning) s.lastSettlement = settlement;
-      if (!live.isRunning && settlement && !s.closedRuns.has(settlement.turnId) && !(event.snapshot && !s.turn)) {
+      if (settlement && !busy) s.lastSettlement = settlement;
+      if (!busy && settlement && !s.closedRuns.has(settlement.turnId) && !(event.snapshot && !s.turn)) {
         if (!s.turn) this.start(s, true);
         // An outgoing prompt needs its echo/reply to identify the native run.
         // Autonomous runs have no outgoing message and may settle silently.
@@ -349,14 +364,13 @@ export class Adapter {
     }
     const turn = s.turn;
     if (turn?.settlement?.outcome === 'success') {
-      const afterSettlement = event.heartbeat && BigInt(event.heartbeat.serverTimeMs ?? 0) > BigInt(turn.settlement.settledAtMs ?? 0);
-      if (turn.hasReply || afterSettlement) await this.completeSettled(s, turn, !!afterSettlement);
+      if (turn.hasReply && !turn.awaitingReply) await this.completeSettled(s, turn);
       else this.settlementGrace(s, turn);
     }
   }
   applySettlement(s, settlement) {
+    if (settlement.outcome === 'success' && s.turn.nativeRunning) return;
     s.turn.settlement = settlement;
-    s.turn.nativeRunning = false;
     if (settlement.outcome === 'cancelled') this.finish(s, 'cancelled');
     else if (settlement.outcome !== 'success') {
       s.turn.failed = true;
@@ -365,7 +379,7 @@ export class Adapter {
     }
   }
   settlementGrace(s, turn) {
-    if (turn.settlementTimer || s.turn !== turn) return;
+    if (turn.settlementTimer || turn.reconciling || turn.nativeRunning || s.turn !== turn) return;
     turn.settlementTimer = this.clock.setTimeout(() => {
       turn.settlementTimer = null;
       void this.completeSettled(s, turn, true).catch(error => {
@@ -373,15 +387,22 @@ export class Adapter {
         s.watch.health.failure(error);
         this.settlementGrace(s, turn);
       });
-    }, SETTLEMENT_GRACE_MS);
+    }, turn.awaitingReply ? ACTIVITY_REPLY_GRACE_MS : SETTLEMENT_GRACE_MS);
   }
-  async completeSettled(s, turn, allowEmpty) {
-    if (s.turn !== turn || turn.reconciling || turn.widgetPending || (!turn.hasReply && !allowEmpty)) return;
+  async completeSettled(s, turn, allowPending = false) {
+    if (s.turn !== turn || turn.reconciling || turn.widgetPending || turn.nativeRunning || !turn.settlement ||
+      ((!turn.hasReply || turn.awaitingReply) && !allowPending)) return;
+    const settlement = turn.settlement;
     turn.reconciling = true;
     try {
       await s.watch.reconcile();
-      if (s.turn === turn && !turn.widgetPending) this.finish(s, 'end_turn');
-    } finally { turn.reconciling = false; }
+      if (s.turn === turn && !turn.widgetPending && !turn.nativeRunning && turn.settlement === settlement) this.finish(s, 'end_turn');
+    } finally {
+      turn.reconciling = false;
+      // A newer idle snapshot or a widget can arrive while history is read.
+      // If it prevented finishing, keep the bounded fallback alive.
+      if (s.turn === turn && turn.settlement?.outcome === 'success') this.settlementGrace(s, turn);
+    }
   }
   async widget(s, turn, entryId, widget) {
     turn.widgetPending = (turn.widgetPending ?? 0) + 1;
@@ -404,7 +425,10 @@ export class Adapter {
   async trace(s, name, args, operation, replyAfter) {
     const turn = s.turn, toolCallId = randomUUID();
     const background = replyAfter !== undefined && !!this.waits;
-    const toolCall = { toolCallId, title: `Coda · ${name}`, kind: 'other', status: 'pending', rawInput: args };
+    // Coda counts read calls without locations as files. Data queries are
+    // other tools, not file reads; telemetry performs an HTTP fetch.
+    const kind = name === 'telemetry' ? 'fetch' : 'other';
+    const toolCall = { toolCallId, title: `Coda · ${name}`, kind, status: 'pending', rawInput: args };
     if (turn) { turn.tools.set(toolCallId, { background }); this.update(s, { sessionUpdate: 'tool_call', ...toolCall }); }
     else this.log(JSON.stringify({ sessionId: s.id, toolCallId, name, arguments: args, state: 'started' }));
     // Register while the initiating turn is still active, before dispatch. The

package/package.json

@@ -3,7 +3,7 @@
   "id": "grok-bot",
   "displayName": "Grok Bot",
   "description": "通过 Grok Bot 原生主会话接入 Coda，镜像回复与 Routine 运行记录。",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "coda": {
     "channels": ["preview"]
   },

package/remote/SKILL.md

@@ -31,9 +31,13 @@ coda_machines 与 coda_machine_diagnostics 由 Coda 内置的「机器诊断」
 
 ## 像用户一样创建工作会话与跟进
 
-需要修复时，先用 coda_agents 确认目标目录、机器与可用 Agent，再用 coda_new_session 创建独立会话。project 必填，使用目录名字或 ID；别的机器上的目录按 ID。默认选择 `agent: "codex"`、`mode: "agent"`，其他 model、effort、options 按任务需要写明；用户在卡片上审阅并批准这些参数。Bot 不设父会话审批档位。
+开会话前先读 `/workspace/.coda-bot/memory/<sessionId>.json`，遵守用户已记录的要求（使用哪个 Agent、哪些问题暂不处理等），并查已有问题与会话，避免重复开。用 coda_agents 确认目标目录、机器与可用 Agent，再用 coda_new_session 创建独立会话；project 必填，使用目录名字或 ID，别的机器上的目录按 ID。Agent 与其他运行参数按用户要求和任务需要选择，由用户在卡片上审阅并批准；Bot 不设父会话审批档位。
 
-prompt 写清证据（会话引用、日志、时间和受影响版本）、重点代码路径、验收方式，以及「按仓库惯例提交、开 PR，并走完 PR 流程直到检查与交叉评审通过」。PR 流程包含检查、交叉评审和评审自动发的评论，都是正常工作；需要修复或重启评审时按流程处理。不要把 Bot 自己的「不要评论／不要开 issue／不要推送」等限制复制进 prompt，也不要限制工作会话走 PR 流程。
+巡检发现问题，先开**归因会话**：只归因，不改代码、不开 PR。prompt 写清现象、证据（会话引用、日志）、时间、受影响版本与重点代码路径，要求给出归因结论、证据链、置信度及是否建议修复。
+
+下次巡检用 coda_read_thread 读归因结论，必要时用 coda_read_tool_call 查证据。确认是需要修复的代码问题，再开**修复会话**；prompt 引用归因会话与结论，写清验收方式，要求「按仓库惯例提交、开 PR，并走完 PR 流程直到检查与交叉评审通过」。结论是偶发、外部因素，或用户说暂不处理的，记进记忆，不开修复会话。
+
+PR 流程包含检查、交叉评审和评审自动发的评论，都是修复会话的正常工作；需要修复或重启评审时按流程处理。不要把 Bot 自己的「不要评论／不要开 issue／不要推送」等限制复制进 prompt，也不要限制修复会话走 PR 流程。
 
 coda_new_session 每次都在 Bot 会话里出允许／拒绝卡片，工具立即返回「已请用户批准；结果会作为新消息告诉你」。不要重复调用或轮询，之后只会收到「已开出：会话引用与标题」「用户拒绝了：标题」，或没开出的「未能开出：标题（原因）」（如目标目录已删除）、「这张卡片已失效，没有开出：标题」，不会收到独立会话之后的工作结果。没开出的按原因查明后再决定是否重新提交，不原样重试。收到开出通知后记下引用，下次巡检用 coda_read_thread 读该会话、必要时 coda_read_tool_call 查看证据；不能用 coda_status 的 children 列表判断独立会话是否存在。
 
@@ -41,7 +45,7 @@ coda_new_session 每次都在 Bot 会话里出允许／拒绝卡片，工具立
 
 如果 Coda 没有提供 new_session，明确告诉用户当前 Coda 不支持创建独立会话，等待升级；不要改用 spawn 或其他手段代替。
 
-把已报告问题的指纹、证据范围、相关会话/修复任务、最后状态按 sessionId 保存在 `/workspace/.coda-bot/memory/<sessionId>.json`。
+把用户对开会话的要求、已报告问题的指纹、证据范围、归因结论、相关会话/修复任务、最后状态按 sessionId 保存在 `/workspace/.coda-bot/memory/<sessionId>.json`。
 同一问题无新证据不重复开任务；先读已记录会话，核实修复、拒绝或失败状态后再决定下一步。
 
 ## 接收委派与明确回传