larkway 0.3.31 → 0.3.33

package/README.md

@@ -8,7 +8,7 @@
 
 You @ the bot in a Feishu thread. It runs on your machine — reading your real codebase, executing commands, opening MRs — and posts the result back. You define what the agent knows and what it can do. Larkway just carries the messages.
 
-**Current release: v0.3.30**
+**Current release: v0.3.33**
 
 ---
 

package/README.zh.md

@@ -8,7 +8,7 @@
 
 你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
 
-**当前版本：v0.3.30**
+**当前版本：v0.3.33**
 
 ---
 

package/dist/main.js

@@ -118306,6 +118306,84 @@ function renderPrompt(input) {
   ].join("\n");
 }
 
+// src/lark/rosterResolver.ts
+import { execFile as execFile2 } from "node:child_process";
+function parseBotRoster(stdout) {
+  const roster = /* @__PURE__ */ new Map();
+  let json2;
+  try {
+    json2 = JSON.parse(stdout);
+  } catch {
+    return roster;
+  }
+  const items = json2?.data?.items;
+  if (!Array.isArray(items)) return roster;
+  for (const item of items) {
+    if (typeof item !== "object" || item === null) continue;
+    const record = item;
+    const name = record["bot_name"];
+    const id = record["bot_id"];
+    if (typeof name === "string" && name && typeof id === "string" && id) {
+      roster.set(name, id);
+    }
+  }
+  return roster;
+}
+function remapPeersToLiveRoster(peers, liveRoster) {
+  const remapped = [];
+  const unresolved = [];
+  const out = peers.map((peer) => {
+    const liveId = liveRoster.get(peer.name);
+    if (!liveId) {
+      unresolved.push(peer.name);
+      return peer;
+    }
+    if (liveId !== peer.id) {
+      remapped.push(peer.name);
+      return { ...peer, id: liveId };
+    }
+    return peer;
+  });
+  return { peers: out, remapped, unresolved };
+}
+async function resolveChatBotRoster(chatId, opts = {}) {
+  const cli = opts.larkCliPath ?? "lark-cli";
+  const args = ["im", "chat.members", "bots", "--chat-id", chatId, "--as", "bot"];
+  if (opts.profile) args.push("--profile", opts.profile);
+  const exec = opts.exec ?? defaultExec(opts.timeoutMs ?? 1e4);
+  try {
+    const stdout = await exec(cli, args);
+    const roster = parseBotRoster(stdout);
+    return roster.size > 0 ? roster : null;
+  } catch {
+    return null;
+  }
+}
+function defaultExec(timeoutMs) {
+  return (cmd, args) => new Promise((resolve2, reject) => {
+    execFile2(cmd, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve2(stdout);
+    });
+  });
+}
+function createCachedRosterResolver(opts) {
+  const ttlMs = opts.ttlMs ?? 5 * 60 * 1e3;
+  const now = opts.now ?? (() => Date.now());
+  const cache = /* @__PURE__ */ new Map();
+  return async (chatId) => {
+    const hit = cache.get(chatId);
+    if (hit && now() - hit.at < ttlMs) return hit.roster;
+    const roster = await resolveChatBotRoster(chatId, {
+      profile: opts.profile,
+      larkCliPath: opts.larkCliPath,
+      exec: opts.exec
+    });
+    cache.set(chatId, { roster, at: now() });
+    return roster;
+  };
+}
+
 // src/agent/runner.ts
 var _registry = /* @__PURE__ */ new Map();
 function registerRunner(backend, factory) {
@@ -119055,7 +119133,30 @@ var StateFileSchema = external_exports.object({
    * ignored and the legacy card path remains authoritative.
    */
   response_surface: ResponseSurfaceStateSchema.optional(),
-  updated_at: external_exports.string()
+  /**
+   * Freshness signal for the handler's stale-guard (it compares this against a
+   * pre-run snapshot to decide whether the bot rewrote state THIS turn).
+   *
+   * **OPTIONAL by thin-channel principle.** This used to be the ONE hard-required
+   * field, so a bot that wrote a perfectly good `status` + `last_message` but
+   * omitted `updated_at` had its ENTIRE state discarded → the card stranded on
+   * "本轮没有拿到 agent 的新回复" every single turn (2026-07-02 排障: one shared
+   * topic reproduced this on every @). Same failure class as the old
+   * `z.string().url()` mr_url and the strict `stage`/`card_color` enums.
+   *
+   * When absent, {@link readStateFileDetailed} server-stamps it from the file's
+   * mtime — which advances only on a real rewrite, so the stale-guard stays
+   * correct even for bots that never write the field.
+   */
+  updated_at: external_exports.string().optional()
+});
+var SalvageStateSchema = external_exports.object({
+  status: external_exports.enum(["in_progress", "ready", "failed"]),
+  last_message: external_exports.string().optional().catch(void 0),
+  error: external_exports.string().optional().catch(void 0),
+  card_title: external_exports.string().optional().catch(void 0),
+  card_text: external_exports.string().optional().catch(void 0),
+  updated_at: external_exports.string().optional().catch(void 0)
 });
 function stateDirOf(worktreePath) {
   return path6.join(worktreePath, ".larkway");
@@ -119093,6 +119194,11 @@ async function readStateFileDetailed(worktreePath) {
     console.warn(`[stateFile] read ${file} failed:`, err);
     return { state: null, diagnostics: [] };
   }
+  let mtimeIso;
+  try {
+    mtimeIso = (await fs3.stat(file)).mtime.toISOString();
+  } catch {
+  }
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -119117,18 +119223,39 @@ async function readStateFileDetailed(worktreePath) {
     }
   }
   const result = StateFileSchema.safeParse(parsed);
-  if (!result.success) {
-    console.warn(
-      `[stateFile] ${file} failed schema validation:`,
-      result.error.issues
-    );
-    return { state: null, diagnostics: [] };
-  }
-  const diagnostics = diagnoseStateFile(parsed, result.data);
-  for (const diagnostic of diagnostics) {
+  if (result.success) {
+    const state = withStampedUpdatedAt(result.data, mtimeIso);
+    const diagnostics = diagnoseStateFile(parsed, result.data);
+    for (const diagnostic of diagnostics) {
+      console.warn(`[stateFile] ${file}: ${diagnostic}`);
+    }
+    return { state, diagnostics };
+  }
+  const salvaged = SalvageStateSchema.safeParse(parsed);
+  if (salvaged.success) {
+    const droppedFields = summarizeRejectedTopFields(result.error);
+    const state = withStampedUpdatedAt(salvaged.data, mtimeIso);
+    const diagnostic = `state.json \u90E8\u5206\u5B57\u6BB5\u65E0\u6548\u5DF2\u5FFD\u7565\uFF0C\u4FDD\u7559 status/last_message\uFF08\u53D7\u5F71\u54CD\u5B57\u6BB5\uFF1A${droppedFields}\uFF09`;
     console.warn(`[stateFile] ${file}: ${diagnostic}`);
+    return { state, diagnostics: [diagnostic] };
+  }
+  console.warn(
+    `[stateFile] ${file} failed schema validation (unsalvageable):`,
+    result.error.issues
+  );
+  return { state: null, diagnostics: [] };
+}
+function withStampedUpdatedAt(state, mtimeIso) {
+  if (state.updated_at != null && state.updated_at !== "") return state;
+  return { ...state, updated_at: mtimeIso ?? (/* @__PURE__ */ new Date()).toISOString() };
+}
+function summarizeRejectedTopFields(error) {
+  const fields = /* @__PURE__ */ new Set();
+  for (const issue of error.issues) {
+    const top = issue.path[0];
+    fields.add(top === void 0 ? "(root)" : String(top));
   }
-  return { state: result.data, diagnostics };
+  return [...fields].join(", ") || "(unknown)";
 }
 function diagnoseStateFile(parsed, state) {
   if (parsed === null || typeof parsed !== "object") return [];
@@ -120132,7 +120259,7 @@ async function ensureNodeModules(worktreePath) {
   if (await pathExists(modulesMarker)) return;
   const start = Date.now();
   try {
-    await execFile2(
+    await execFile3(
       "pnpm",
       ["install", "--offline", "--frozen-lockfile"],
       { cwd: monorepDir, timeoutMs: 18e4 }
@@ -120146,7 +120273,7 @@ async function ensureNodeModules(worktreePath) {
       `[bridge.handler] --offline install failed (will fall back to network): ${offlineErr.message.slice(0, 200)}`
     );
   }
-  await execFile2(
+  await execFile3(
     "pnpm",
     ["install", "--frozen-lockfile"],
     { cwd: monorepDir, timeoutMs: 6e5 }
@@ -120155,7 +120282,7 @@ async function ensureNodeModules(worktreePath) {
     `[bridge.handler] pnpm install (network) ok (${((Date.now() - start) / 1e3).toFixed(1)}s) in ${monorepDir}`
   );
 }
-function execFile2(cmd, args, opts) {
+function execFile3(cmd, args, opts) {
   return new Promise((resolve2, reject) => {
     const child = child_process.spawn(cmd, args, {
       cwd: opts.cwd,
@@ -120223,9 +120350,30 @@ async function createOnlyPostFallback(opts) {
 var BridgeHandler = class {
   deps;
   closed = false;
+  /**
+   * In-flight per-turn completion promises. run() dispatches handleOne
+   * fire-and-forget (thread-serialized), so run() returning does NOT mean the
+   * turn finished. Each entry resolves only when its handleOne AND all trailing
+   * work (terminal render + ledger writes, incl. the failure-path fallback that
+   * runs after the early settle) have completed. {@link whenAllTurnsSettled}
+   * awaits these — the real turn boundary tests must sync assertions/cleanup on.
+   */
+  inFlightTurns = /* @__PURE__ */ new Set();
   constructor(deps) {
     this.deps = deps;
   }
+  /**
+   * Resolves when every dispatched turn has fully completed (handleOne returned
+   * and its trailing render/ledger I/O drained). Test-facing sync point; a bridge
+   * that keeps receiving events would keep finding work, so callers use this
+   * after the event source is exhausted (e.g. right after `await run()` in a
+   * single-message test).
+   */
+  async whenAllTurnsSettled() {
+    while (this.inFlightTurns.size > 0) {
+      await Promise.all([...this.inFlightTurns]);
+    }
+  }
   runtimeWarnings() {
     return (this.deps.runtimeRequirements ?? []).filter(
       (req) => !req.ok && (req.severity === "required" || req.kind === "secret")
@@ -120276,7 +120424,9 @@ var BridgeHandler = class {
       }).finally(() => {
         release();
         if (threadQueues.get(key) === next) threadQueues.delete(key);
+        this.inFlightTurns.delete(next);
       });
+      this.inFlightTurns.add(next);
       threadQueues.set(key, next);
     }
   }
@@ -120659,6 +120809,34 @@ var BridgeHandler = class {
         while (true) {
           attempt++;
           const currentIsNewThread = currentExisting === void 0;
+          let effectivePeers = this.deps.peers;
+          if (effectivePeers?.length && this.deps.resolveLiveRoster) {
+            try {
+              const liveRoster = await this.deps.resolveLiveRoster(parsed.chatId);
+              if (liveRoster) {
+                const { peers: remappedPeers, remapped, unresolved } = remapPeersToLiveRoster(
+                  effectivePeers,
+                  liveRoster
+                );
+                effectivePeers = remappedPeers;
+                if (remapped.length > 0 || unresolved.length > 0) {
+                  await recordEvent({
+                    status: "running",
+                    appendPath: "peer roster",
+                    reason: `live-roster resolve: remapped [${remapped.join(", ") || "none"}] to same-app-scope open_id; unresolved (kept static config id, may not be deliverable) [${unresolved.join(", ") || "none"}].`
+                  });
+                }
+              } else {
+                await recordEvent({
+                  status: "running",
+                  appendPath: "peer roster",
+                  reason: "live-roster resolve returned nothing; kept static <peer-bots> open_ids (may be cross-app-scope / undeliverable)."
+                });
+              }
+            } catch (err) {
+              console.warn("[bridge.handler] live-roster resolve failed (using static peers):", err);
+            }
+          }
           const prompt = renderPrompt({
             parsed,
             isNewThread: currentIsNewThread,
@@ -120680,7 +120858,7 @@ var BridgeHandler = class {
               readOnly: conventions.readOnly,
               gitlabTokenEnvName: conventions.gitlabTokenEnvName
             },
-            peers: this.deps.peers,
+            peers: effectivePeers,
             turn_taking_limit: this.deps.botConfig?.turn_taking_limit,
             botName: this.deps.botConfig?.name,
             backend: this.deps.botConfig?.backend,
@@ -120823,7 +121001,9 @@ var BridgeHandler = class {
               });
             }
             const fallbackAnswer = trustedAnswerText.trim() || cardKitProgress?.answerText.trim() || "";
-            const cardBody = cardKitTimeoutFailure ? "\u26A0\uFE0F \u672C\u8F6E\u88AB\u4E2D\u65AD\uFF08\u957F\u65F6\u95F4\u65E0\u6D3B\u6027\uFF0C\u5224\u5B9A\u5361\u6B7B\uFF09\uFF0C\u672A\u5B8C\u6210\u3002\u8BF7\u91CD\u8BD5\u3002" : reportedState?.last_message ?? (fallbackAnswer ? fallbackAnswer : "\u26A0\uFE0F \u672C\u8F6E\u6CA1\u6709\u62FF\u5230 agent \u7684\u65B0\u56DE\u590D(\u53EF\u80FD\u88AB\u4E2D\u65AD\u6216\u672A\u66F4\u65B0\u72B6\u6001),\u518D @ \u6211\u4E00\u6B21\u91CD\u8BD5\u3002");
+            const noOutputFallback = "\u26A0\uFE0F \u672C\u8F6E agent \u6CA1\u6709\u4EA7\u51FA\u6B63\u6587\uFF0C\u4E5F\u6CA1\u6709\u5199\u5165\u6709\u6548\u72B6\u6001(state.json)\u3002\n" + (result.exitCode !== 0 ? `agent \u8FDB\u7A0B\u5F02\u5E38\u9000\u51FA(exit code ${result.exitCode})\u3002
+` : "") + "\u4E0B\u4E00\u6B65\uFF1A\u6362\u4E2A\u8BF4\u6CD5\u91CD\u8BD5\uFF0C\u6216\u65B0\u5F00\u4E00\u4E2A\u8BDD\u9898\u7EE7\u7EED\uFF1B\u82E5\u53CD\u590D\u5982\u6B64\uFF0C\u8BF7\u8BA9\u7EF4\u62A4\u8005\u67E5\u770B\u8BE5 session \u65E5\u5FD7\u3002";
+            const cardBody = cardKitTimeoutFailure ? "\u26A0\uFE0F \u672C\u8F6E\u88AB\u4E2D\u65AD\uFF08\u957F\u65F6\u95F4\u65E0\u6D3B\u6027\uFF0C\u5224\u5B9A\u5361\u6B7B\uFF09\uFF0C\u672A\u5B8C\u6210\u3002\u8BF7\u91CD\u8BD5\u3002" : reportedState?.last_message ?? (fallbackAnswer ? fallbackAnswer : noOutputFallback);
             const noReportThisTurn = reportedState === null;
             const neutralTitle = noReportThisTurn && success && !failureReason ? "\u{1F4AC} \u5DF2\u56DE\u590D" : void 0;
             const baseCardPayload = {
@@ -126297,6 +126477,9 @@ async function runV2Mode({
       gitlabToken: effectiveGitlabToken,
       agentMemory: bot.agent_memory,
       larkCliProfile,
+      // PRB-6/§11.3: resolve peer @ targets to same-app-scope open_ids from the
+      // live chat roster (per-chat cached), only when this bot actually has peers.
+      resolveLiveRoster: resolvedPeers.length > 0 ? createCachedRosterResolver({ profile: larkCliProfile }) : void 0,
       runtimeRequirements: runtimeRequirementsForBots([bot]),
       recordRuntimeEvent: async (patch) => {
         await upsertRuntimeEvent(larkwayHome(), bot.id, patch);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkway",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "description": "Thin bridge: Feishu thread to local Claude Code CLI",
   "license": "MIT",
   "author": "Chuck Wu (chuckwu0)",