larkway 0.3.24 → 0.3.25

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.24**
+**Current release: v0.3.25**
 
 ---
 

package/README.zh.md

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

package/dist/main.js

@@ -119111,6 +119111,20 @@ async function deleteCardFile(worktreePath) {
 // src/bridge/cardkitFile.ts
 import fs5 from "node:fs/promises";
 import path8 from "node:path";
+var defaultCardKitLiveMetrics = () => ({
+  answerDeltaCount: 0,
+  answerSnapshotCount: 0,
+  firstAnswerAt: null,
+  lastAnswerAt: null,
+  visibleAnswerLength: 0,
+  toolUseCount: 0,
+  lastToolUseAt: null,
+  statusPatchCount: 0,
+  lastStatusPatchAt: null,
+  progressUpdateCount: 0,
+  lastProgressPatchAt: null,
+  lastPatchError: null
+});
 var CardKitFileSchema = external_exports.object({
   surface: external_exports.literal("cardkit_stream"),
   status: external_exports.enum(["planned", "message_sent", "streaming", "finalized", "fallback_visible", "failed"]).default("planned"),
@@ -119124,6 +119138,20 @@ var CardKitFileSchema = external_exports.object({
   replyInThread: external_exports.boolean().default(true),
   idempotencyKey: external_exports.string().min(1),
   sequence: external_exports.number().int().nonnegative().default(0),
+  live: external_exports.object({
+    answerDeltaCount: external_exports.number().int().nonnegative().default(0),
+    answerSnapshotCount: external_exports.number().int().nonnegative().default(0),
+    firstAnswerAt: external_exports.string().min(1).nullable().default(null),
+    lastAnswerAt: external_exports.string().min(1).nullable().default(null),
+    visibleAnswerLength: external_exports.number().int().nonnegative().default(0),
+    toolUseCount: external_exports.number().int().nonnegative().default(0),
+    lastToolUseAt: external_exports.string().min(1).nullable().default(null),
+    statusPatchCount: external_exports.number().int().nonnegative().default(0),
+    lastStatusPatchAt: external_exports.string().min(1).nullable().default(null),
+    progressUpdateCount: external_exports.number().int().nonnegative().default(0),
+    lastProgressPatchAt: external_exports.string().min(1).nullable().default(null),
+    lastPatchError: external_exports.string().min(1).nullable().default(null)
+  }).default(defaultCardKitLiveMetrics),
   elements: external_exports.object({
     status: external_exports.object({ elementId: external_exports.string().min(1) }).optional(),
     thinking: external_exports.object({ elementId: external_exports.string().min(1) }).optional(),
@@ -119354,6 +119382,29 @@ function isMissingCardKitElementError(err) {
   const message = err.message.toLowerCase();
   return message.includes("element") && (message.includes("not found") || message.includes("not exist") || message.includes("\u4E0D\u5B58\u5728"));
 }
+function initialLiveMetrics() {
+  return {
+    answerDeltaCount: 0,
+    answerSnapshotCount: 0,
+    firstAnswerAt: null,
+    lastAnswerAt: null,
+    visibleAnswerLength: 0,
+    toolUseCount: 0,
+    lastToolUseAt: null,
+    statusPatchCount: 0,
+    lastStatusPatchAt: null,
+    progressUpdateCount: 0,
+    lastProgressPatchAt: null,
+    lastPatchError: null
+  };
+}
+function summarizeError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.replace(/\s+/g, " ").trim().slice(0, 240) || "unknown error";
+}
+function toolStatusText(toolUseCount) {
+  return toolUseCount > 0 ? `\u52AA\u529B\u56DE\u7B54\u4E2D... \xB7 \u5DF2\u7528 ${toolUseCount} \u4E2A\u5DE5\u5177` : "\u52AA\u529B\u56DE\u7B54\u4E2D...";
+}
 var LiveCardKitProgressHandle = class {
   cardId;
   messageId;
@@ -119362,12 +119413,14 @@ var LiveCardKitProgressHandle = class {
   patchIntervalMs;
   maxProgressUpdates;
   onSequenceCommitted;
+  onLiveMetricsChanged;
   answerBuffer = "";
   pendingPatch = null;
   inFlight = Promise.resolve();
   closed = false;
-  progressUpdates = 0;
   answerElementCreated = false;
+  immediatePatchStarted = false;
+  metrics = initialLiveMetrics();
   sequence = 0;
   constructor(opts) {
     this.cardKitClient = opts.cardKitClient;
@@ -119377,20 +119430,31 @@ var LiveCardKitProgressHandle = class {
     this.patchIntervalMs = opts.patchIntervalMs;
     this.maxProgressUpdates = opts.maxProgressUpdates;
     this.onSequenceCommitted = opts.onSequenceCommitted;
+    this.onLiveMetricsChanged = opts.onLiveMetricsChanged;
   }
   get answerText() {
     return this.answerBuffer;
   }
+  get liveMetrics() {
+    return { ...this.metrics };
+  }
   handle(event) {
     if (this.closed) return;
+    if (event.type === "tool_use") {
+      this.recordToolUse();
+      this.patchStatus(toolStatusText(this.metrics.toolUseCount));
+      return;
+    }
     if (event.type === "answer_delta") {
       this.answerBuffer += event.text;
-      this.schedulePatch();
+      this.recordAnswerEvent("answer_delta");
+      this.schedulePatch({ immediate: !this.immediatePatchStarted });
       return;
     }
     if (event.type === "answer_snapshot") {
       this.answerBuffer = event.text;
-      this.schedulePatch();
+      this.recordAnswerEvent("answer_snapshot");
+      this.schedulePatch({ immediate: !this.immediatePatchStarted });
     }
   }
   async drain() {
@@ -119449,8 +119513,71 @@ var LiveCardKitProgressHandle = class {
       this.pendingPatch = null;
     }
   }
-  schedulePatch() {
-    if (this.pendingPatch || this.progressUpdates >= this.maxProgressUpdates) return;
+  recordAnswerEvent(type2) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (type2 === "answer_delta") {
+      this.metrics.answerDeltaCount += 1;
+    } else {
+      this.metrics.answerSnapshotCount += 1;
+    }
+    this.metrics.firstAnswerAt ??= now;
+    this.metrics.lastAnswerAt = now;
+    this.metrics.visibleAnswerLength = this.answerBuffer.length;
+    this.emitLiveMetrics();
+    console.info(
+      "[cardkit_progress] answer event",
+      `type=${type2}`,
+      `delta_count=${this.metrics.answerDeltaCount}`,
+      `snapshot_count=${this.metrics.answerSnapshotCount}`,
+      `visible_length=${this.metrics.visibleAnswerLength}`,
+      `sequence=${this.sequence}`
+    );
+  }
+  recordToolUse() {
+    this.metrics.toolUseCount += 1;
+    this.metrics.lastToolUseAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.emitLiveMetrics();
+    console.info(
+      "[cardkit_progress] tool event",
+      `tool_use_count=${this.metrics.toolUseCount}`,
+      `sequence=${this.sequence}`
+    );
+  }
+  patchStatus(content) {
+    this.inFlight = this.inFlight.then(
+      () => this.next(
+        (sequence) => this.cardKitClient.updateElement(
+          this.cardId,
+          CARDKIT_FOOTER_ELEMENT_ID,
+          {
+            tag: "markdown",
+            content,
+            element_id: CARDKIT_FOOTER_ELEMENT_ID
+          },
+          {
+            sequence,
+            uuid: sequenceUuid(this.cardId, "status", sequence)
+          }
+        )
+      )
+    ).then(() => {
+      this.metrics.statusPatchCount += 1;
+      this.metrics.lastStatusPatchAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.metrics.lastPatchError = null;
+      this.emitLiveMetrics();
+    }).catch((err) => {
+      this.metrics.lastPatchError = summarizeError(err);
+      this.emitLiveMetrics();
+      console.warn("[cardkit_progress] status update failed (continuing):", err);
+    });
+  }
+  schedulePatch(opts = {}) {
+    if (this.pendingPatch || this.metrics.progressUpdateCount >= this.maxProgressUpdates) return;
+    if (opts.immediate) {
+      this.immediatePatchStarted = true;
+      void this.patchProgress();
+      return;
+    }
     this.pendingPatch = setTimeout(() => {
       this.pendingPatch = null;
       void this.patchProgress();
@@ -119458,9 +119585,8 @@ var LiveCardKitProgressHandle = class {
     this.pendingPatch.unref?.();
   }
   async patchProgress() {
-    if (this.closed || this.progressUpdates >= this.maxProgressUpdates) return;
+    if (this.closed || this.metrics.progressUpdateCount >= this.maxProgressUpdates) return;
     if (!this.answerBuffer) return;
-    this.progressUpdates += 1;
     this.inFlight = this.inFlight.then(
       () => this.withAnswerElement(this.answerBuffer).then(
         () => this.next(
@@ -119470,7 +119596,21 @@ var LiveCardKitProgressHandle = class {
           })
         )
       )
-    ).catch((err) => {
+    ).then(() => {
+      this.metrics.progressUpdateCount += 1;
+      this.metrics.visibleAnswerLength = this.answerBuffer.length;
+      this.metrics.lastProgressPatchAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.metrics.lastPatchError = null;
+      this.emitLiveMetrics();
+      console.info(
+        "[cardkit_progress] progress committed",
+        `progress_update_count=${this.metrics.progressUpdateCount}`,
+        `visible_length=${this.metrics.visibleAnswerLength}`,
+        `sequence=${this.sequence}`
+      );
+    }).catch((err) => {
+      this.metrics.lastPatchError = summarizeError(err);
+      this.emitLiveMetrics();
       console.warn("[cardkit_progress] progress update failed (continuing):", err);
     });
     await this.inFlight;
@@ -119496,6 +119636,9 @@ var LiveCardKitProgressHandle = class {
     await fn(this.sequence);
     await this.onSequenceCommitted?.(this.sequence);
   }
+  emitLiveMetrics() {
+    this.onLiveMetricsChanged?.({ ...this.metrics, sequence: this.sequence });
+  }
 };
 async function createCardKitProgressHandle(opts) {
   const key = idempotencyKey(opts.facts);
@@ -119529,7 +119672,8 @@ async function createCardKitProgressHandle(opts) {
     idempotencyKey: key,
     patchIntervalMs: opts.patchIntervalMs ?? DEFAULT_PATCH_INTERVAL_MS,
     maxProgressUpdates: opts.maxProgressUpdates ?? DEFAULT_MAX_PROGRESS_UPDATES,
-    onSequenceCommitted: opts.onSequenceCommitted
+    onSequenceCommitted: opts.onSequenceCommitted,
+    onLiveMetricsChanged: opts.onLiveMetricsChanged
   });
 }
 async function finalizeExistingCardKitCard(opts) {
@@ -120603,6 +120747,7 @@ var ResponseSurfacePostBudget = class {
 };
 
 // src/bridge/handler.ts
+var DEFAULT_CARDKIT_RESPONSE_SURFACE_TIMEOUT_MS = 20 * 60 * 1e3;
 function execGit(cwd, args) {
   return new Promise((resolve2, reject) => {
     const child = child_process.spawn("git", args, {
@@ -121157,6 +121302,7 @@ var BridgeHandler = class {
         } catch (err) {
           console.warn("[bridge.handler] ensureStateFile failed (continuing):", err);
         }
+        let cardKitRecordWrite = Promise.resolve();
         const updateCardKitRecord = async (patch) => {
           if (!cardKitRecord) return;
           cardKitRecord = {
@@ -121164,7 +121310,16 @@ var BridgeHandler = class {
             ...patch,
             updatedAt: (/* @__PURE__ */ new Date()).toISOString()
           };
-          await writeCardKitFile(worktreePath, cardKitRecord);
+          const record = cardKitRecord;
+          cardKitRecordWrite = cardKitRecordWrite.catch(() => {
+          }).then(() => writeCardKitFile(worktreePath, record));
+          await cardKitRecordWrite;
+        };
+        const updateCardKitLiveMetrics = (metrics) => {
+          const { sequence, ...live } = metrics;
+          void updateCardKitRecord({ sequence, live }).catch((err) => {
+            console.warn("[bridge.handler] write CardKit live metrics failed:", err);
+          });
         };
         if (!card && cardKitAvailable && this.deps.cardKitClient) {
           try {
@@ -121180,7 +121335,8 @@ var BridgeHandler = class {
               initialStatusText: "\u52AA\u529B\u56DE\u7B54\u4E2D...",
               onSequenceCommitted: async (sequence) => {
                 await updateCardKitRecord({ status: "streaming", sequence });
-              }
+              },
+              onLiveMetricsChanged: updateCardKitLiveMetrics
             });
             cardKitRecord = {
               surface: "cardkit_stream",
@@ -121195,6 +121351,7 @@ var BridgeHandler = class {
               replyInThread,
               idempotencyKey: cardKitProgress.idempotencyKey,
               sequence: cardKitProgress.sequence,
+              live: cardKitProgress.liveMetrics,
               elements: {
                 footer: { elementId: "footer_md" },
                 final: { elementId: "final_md" }
@@ -121362,7 +121519,12 @@ var BridgeHandler = class {
           });
           const backend = this.deps.botConfig?.backend ?? "claude";
           const permissionMode = this.deps.permissionMode ?? "bypassPermissions";
-          const timeoutMs = this.deps.subprocessTimeoutMs ?? 60 * 60 * 1e3;
+          const baseTimeoutMs = this.deps.subprocessTimeoutMs ?? 60 * 60 * 1e3;
+          const timeoutMs = cardKitProgress ? Math.min(
+            baseTimeoutMs,
+            this.deps.responseSurfaceTimeoutMs ?? DEFAULT_CARDKIT_RESPONSE_SURFACE_TIMEOUT_MS
+          ) : baseTimeoutMs;
+          const runnerStartedAt = Date.now();
           const handle = createRunner(backend).run({
             prompt,
             resumeSessionId: currentExisting?.sessionId,
@@ -121390,6 +121552,7 @@ var BridgeHandler = class {
               }
             }
             const result = await handle.done;
+            const cardKitTurnTimedOut = cardKitProgress != null && result.exitCode !== 0 && Date.now() - runnerStartedAt >= timeoutMs;
             const rawReportedState = await readStateFile(worktreePath);
             const reportedState = rawReportedState?.updated_at != null && rawReportedState.updated_at !== preRunUpdatedAt ? rawReportedState : null;
             const now = Date.now();
@@ -121419,6 +121582,7 @@ var BridgeHandler = class {
             }
             const reportedStatus = reportedState?.status;
             const reportedError = reportedState?.error;
+            const cardKitTimeoutFailure = cardKitTurnTimedOut && reportedStatus !== "ready" && reportedStatus !== "failed";
             let success;
             let failureReason;
             if (reportedStatus === "failed") {
@@ -121426,6 +121590,9 @@ var BridgeHandler = class {
               failureReason = reportedError ?? "bot \u62A5\u544A failed (\u65E0 error \u5B57\u6BB5)";
             } else if (reportedStatus === "ready") {
               success = true;
+            } else if (cardKitTimeoutFailure) {
+              success = false;
+              failureReason = `agent turn timed out after ${timeoutMs}ms; CardKit running card was finalized as interrupted`;
             } else if (result.exitCode === 0) {
               success = true;
             } else {
@@ -121433,14 +121600,14 @@ var BridgeHandler = class {
               failureReason = `claude exited ${result.exitCode} \u4E14 bot \u672A\u66F4\u65B0 state.json status \u2014 \u53EF\u80FD\u5D29\u6E83`;
             }
             const fallbackAnswer = trustedAnswerText.trim() || cardKitProgress?.answerText.trim() || "";
-            const cardBody = 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 cardBody = cardKitTimeoutFailure ? "\u26A0\uFE0F \u672C\u8F6E\u5904\u7406\u8D85\u65F6\uFF0C\u5DF2\u4E2D\u65AD\u3002\u8BF7\u518D @ \u6211\u4E00\u6B21\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 noReportThisTurn = reportedState === null;
             const neutralTitle = noReportThisTurn && success && !failureReason ? "\u{1F4AC} \u5DF2\u56DE\u590D" : void 0;
             const baseCardPayload = {
               finalText: cardBody,
               success,
               failureReason,
-              titleOverride: reportedState?.card_title ?? neutralTitle,
+              titleOverride: reportedState?.card_title ?? (cardKitTimeoutFailure ? "\u5DF2\u4E2D\u65AD" : neutralTitle),
               colorOverride: reportedState?.card_color ?? (neutralTitle ? "neutral" : void 0),
               // V2 dynamic-choice buttons — agent-declared, rendered verbatim.
               // reportedState is null when state.json wasn't freshly written

package/package.json

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