openclaw-lark-multi-agent 1.1.2 → 1.2.1

package/README.md

@@ -37,6 +37,7 @@ All of them connect to the same OpenClaw Gateway while keeping sessions, queues,
 - Feishu image download and OpenClaw multimodal attachment forwarding
 - Bridge attachment marker protocol for generated files/images/documents
 - Feishu CardKit v2 Markdown rendering, including native table elements for pipe tables
+- Live status card: in non-verbose mode each run shows a single self-updating Feishu interactive card (title + recent activity window with per-line timestamps + elapsed/model footer, refreshed once per second), which collapses to a compact one-line summary on a clean finish and retains the recent activity on failure for debugging
 - Bridge-level slash commands and escaped OpenClaw slash commands
 - `/discuss` mode for barrier-style multi-bot group discussion, including per-round markers and no-reply status notices
 - `/chairman` role: a single per-group chairman that answers plain messages when no bot is in Free mode, and acts as host, challenger, and summarizer inside `/discuss`
@@ -231,10 +232,13 @@ Bridge-level commands use a single slash and are handled by this project:
 - `/status` — show bot model, token usage, and session state
 - `/compact` — compact the OpenClaw session
 - `/reset` — reset the OpenClaw session
+- `/stop` — force-stop a stuck run for this bot in this chat and unlock the queue
 - `/verbose` — toggle tool-call messages for this bot in this chat
+- `/livestatus [on|off]` — toggle, or explicitly enable/disable, the self-updating run-status card shown in non-verbose mode (default on)
 - `/free [on|off]` — toggle, or explicitly enable/disable, this bot's Free mode in the current group chat
 - `/mute` — toggle this bot's mute mode in the current group chat
 - `/mode` — show this bot's current mode in the current chat
+- `/model [id]` — show or switch this bot's bound model (persisted)
 - `/discuss on|off|status|stop|rounds N` — control group-level multi-bot discussion mode (requires a chairman to enable; default 10 rounds)
 - `/chairman [@Bot|off]` — set, view, or clear the single chairman for this group
 - `/locale [zh|en]` — set or view this group's language
@@ -323,7 +327,7 @@ Persistent constraints (such as "do not call Feishu send tools directly" and the
 `/discuss` is an explicit group-level multi-agent discussion scheduler. It is separate from Free mode:
 
 - `/free` controls whether a single bot may answer plain human messages.
-- `/discuss on` requires a chairman to be set first (`/chairman @Bot`). It lets one coordinator take over plain human messages and run all Free-mode bots plus the chairman in barrier-style rounds.
+- `/discuss on` requires a chairman to be set first (`/chairman @Bot`). It lets one coordinator take over plain human messages and run all non-muted bots plus the chairman in barrier-style rounds. Free mode is ignored inside discussion: every bot that is not muted participates regardless of its Free setting.
 - Targeted mentions still fall through to normal routing, so `@GPT hello` works even while discuss mode is enabled.
 - Each participant receives the same round prompt and does not see other participants' replies from the current round until the next round.
 - The chairman speaks last each round: it gives its own view, challenges weak points, mediates disagreements, and decides whether to continue or conclude.
@@ -396,6 +400,23 @@ The bridge subscribes to Feishu `im.message.recalled_v1` events. When a user rec
 
 Version 1 behavior intentionally does **not** abort an OpenClaw run that has already started processing the recalled message, and it does not recall bot replies that were already sent. The first goal is to make recall reliable for queued/not-yet-processed messages.
 
+## Session health and error recovery
+
+The bridge distinguishes a failed *run* from a dead *session*:
+
+- During an active run, a health monitor polls the OpenClaw session. Only true
+  session-death states (`killed` / `dead` / `crashed`, matched on word
+  boundaries) are treated as unhealthy; run-level outcomes such as `aborted`,
+  `error`, or `timeout` are not, because the session usually remains usable for
+  the next message. A short re-check guards against transient blips.
+- When a session is genuinely unhealthy, the bridge warns the user but does not
+  force a `/reset`: the current message is still attempted, and only an in-run
+  confirmation of death stops the wait. Users decide whether to retry.
+- Recoverable agent errors are not surfaced as failures. When OpenClaw emits a
+  recoverable lifecycle error (for example `Context overflow: prompt too large`)
+  it auto-compacts and keeps the same run alive; the bridge defers instead of
+  rejecting, so a later real final reply wins. Only a genuine stall falls back to
+  the deferred error via the idle timeout. Non-recoverable errors still fail fast.
 
 ## Markdown, tables, and attachments
 
@@ -408,6 +429,50 @@ Assistant replies are sent as Feishu CardKit v2 cards. Markdown is preprocessed
 
 For generated files/images/documents, agents should use the bridge attachment marker protocol instead of calling Feishu messaging tools directly. The bridge strips the marker from the visible reply, validates the file path under the configured attachment directory, uploads/sends the attachment, and records it in local context. Markdown documents can be converted into Feishu cloud documents through this path.
 
+## Live status
+
+In non-verbose mode, each run shows a single self-updating Feishu interactive
+card so users can see progress without the noise of per-tool-call messages.
+Verbose mode and live status are mutually exclusive: when `/verbose` is on, the
+bridge emits the existing per-tool messages instead of a live status card.
+
+While running, the card shows:
+
+- a title (`<bot> is working`);
+- a rolling window of the most recent activity lines (tool start `▸`, tool end
+  `✓`, and intermediate assistant text `•`), each prefixed with the relative
+  time `mm:ss` since the run started;
+- a footer with elapsed time and the bound model name.
+
+The card is created lazily (a fast reply that finishes within the create delay
+never spawns a card, to avoid flicker) and is updated with `im.message.patch`,
+which has no 20-edit cap. A 1-second ticker advances the elapsed timer even when
+no new activity arrives.
+
+When the run ends:
+
+- a clean finish (normal reply or `NO_REPLY`) collapses the card to a single
+  compact grey line: status emoji + total tool calls + total elapsed;
+- a failure (provider error, killed/unhealthy session, delivery error, or idle
+  timeout) keeps the recent activity window plus the summary, with an orange
+  header, so the steps leading up to the failure stay visible for debugging.
+
+The final answer is always delivered separately through the normal interactive-card
+delivery path, so Markdown renders correctly; the live status card is a distinct
+message and never replaces or blocks the final reply.
+
+Live status is on by default and can be toggled per bot/chat with
+`/livestatus [on|off]`. It can be disabled globally by setting
+`OPENCLAW_LARK_MULTI_AGENT_LIVE_STATUS=0`. Tunable defaults:
+
+| Environment variable | Default | Meaning |
+| --- | --- | --- |
+| `OPENCLAW_LARK_MULTI_AGENT_LIVE_STATUS` | `1` | Master switch; `0` disables live status for all bots |
+| `OPENCLAW_LARK_MULTI_AGENT_LIVE_STATUS_DELAY_MS` | `800` | Delay before creating the card, so fast replies do not flicker one |
+| `OPENCLAW_LARK_MULTI_AGENT_LIVE_STATUS_TICK_MS` | `1000` | How often the elapsed-time footer auto-refreshes |
+| `OPENCLAW_LARK_MULTI_AGENT_LIVE_STATUS_HISTORY` | `6` | Number of recent activity lines kept in the card |
+| `OPENCLAW_LARK_MULTI_AGENT_LIVE_STATUS_MAX_CHARS` | `120` | Per-line character cap before truncation |
+
 ## Data model
 
 SQLite state lives in the configured data directory. Important tables:
@@ -421,7 +486,7 @@ SQLite state lives in the configured data directory. Important tables:
 - `delivery_outbox` — durable user-visible delivery ledger with claim/dedupe state
 - `recalled_messages` — recalled user messages excluded from pending work and future context
 - `processed_events` — Feishu event de-duplication
-- `bot_chat_settings` — per-bot/per-chat settings such as verbose mode
+- `bot_chat_settings` — per-bot/per-chat settings such as verbose mode, mode, and live-status toggle
 
 ## Development
 

package/dist/compact-progress.d.ts

@@ -0,0 +1,75 @@
+/** Coarse phase of the compaction flow, drives the card's primary line. */
+export type CompactPhase = "native" | "tool-trim";
+/** Terminal outcome used by the renderer to pick color/emoji. */
+export type CompactState = "running" | "done" | "failed" | "noop";
+/** Structured snapshot the renderer turns into a Feishu interactive card. */
+export type CompactProgressView = {
+    state: CompactState;
+    /** Current phase while running (ignored once terminal). */
+    phase: CompactPhase;
+    /** Elapsed time like "0:42". */
+    elapsed: string;
+    /** Terminal detail line, e.g. "12.3M→4.1M (-67%)" or an error/skip reason. */
+    detail?: string;
+};
+export type CompactProgressCallbacks = {
+    /** Create the status card; returns the new message id (undefined disables). */
+    create: (view: CompactProgressView) => Promise<string | undefined>;
+    /** Patch the existing status card. */
+    edit: (messageId: string, view: CompactProgressView) => Promise<void>;
+    warn?: (message: string, err?: unknown) => void;
+};
+export type CompactProgressOptions = {
+    locale?: "zh" | "en";
+    /** Delay before the card first appears, to avoid flashing on fast compactions. */
+    delayMs?: number;
+    /** Footer/auto-refresh cadence in ms. */
+    tickMs?: number;
+};
+/**
+ * Lifecycle: start() → (optional) toToolTrim() when native gives up → one of
+ * done()/noop()/fail(). The card is created lazily after `delayMs` so a fast
+ * compaction that finishes first never shows a card at all. All terminal calls
+ * are idempotent and safe even if the card was never created.
+ */
+export declare class CompactProgressController {
+    private readonly callbacks;
+    private readonly opts;
+    private messageId?;
+    private startedAt;
+    private phase;
+    private state;
+    private detail?;
+    private createTimer?;
+    private tickTimer?;
+    private createPromise?;
+    private finalized;
+    private disabled;
+    private lastSignature;
+    constructor(callbacks: CompactProgressCallbacks, opts?: CompactProgressOptions);
+    get id(): string | undefined;
+    /** Begin the flow; schedules lazy card creation after delayMs. */
+    start(): void;
+    /** Native compaction gave up (timeout/no-op); switch the card to fast-trim. */
+    toToolTrim(): Promise<void>;
+    /** Finished successfully; patch the card to the done state with a detail line. */
+    done(detail?: string): Promise<void>;
+    /** Nothing to compact; patch the card to a neutral "no-op" state. */
+    noop(detail?: string): Promise<void>;
+    /** Failed; patch the card to the failed state with an error detail line. */
+    fail(detail?: string): Promise<void>;
+    /** Tear down timers without sending anything (e.g. on unexpected disposal). */
+    dispose(): void;
+    private finish;
+    private refresh;
+    private ensureCreatedNow;
+    private ensureCreated;
+    /** Refresh the elapsed-time footer periodically even with no phase change. */
+    private startTicker;
+    private safeEdit;
+    private stopTimers;
+    /** Dedupe key; includes elapsed so the ticking footer still advances. */
+    private signature;
+    private formatElapsed;
+    buildView(): CompactProgressView;
+}

package/dist/compact-progress.js

@@ -0,0 +1,177 @@
+// A tiny live-status controller dedicated to the /compact (and auto-compact)
+// flow, so the user gets a visible "正在压缩…" card that ticks while a large
+// session is being compacted — instead of staring at nothing for tens of
+// seconds while native compaction grinds (and sometimes times out).
+//
+// It deliberately does NOT reuse LiveStatusController: that one models a tool
+// run (activity window, tool-call count, model footer). Compaction has just a
+// few coarse phases and a single elapsed timer, so a focused, self-contained
+// controller keeps the card clean and the logic trivial to test.
+const DEFAULT_DELAY_MS = Number(process.env.OPENCLAW_LARK_MULTI_AGENT_COMPACT_STATUS_DELAY_MS || 500);
+const DEFAULT_TICK_MS = Number(process.env.OPENCLAW_LARK_MULTI_AGENT_COMPACT_STATUS_TICK_MS || 1000);
+/**
+ * Lifecycle: start() → (optional) toToolTrim() when native gives up → one of
+ * done()/noop()/fail(). The card is created lazily after `delayMs` so a fast
+ * compaction that finishes first never shows a card at all. All terminal calls
+ * are idempotent and safe even if the card was never created.
+ */
+export class CompactProgressController {
+    callbacks;
+    opts;
+    messageId;
+    startedAt = Date.now();
+    phase = "native";
+    state = "running";
+    detail;
+    createTimer;
+    tickTimer;
+    createPromise;
+    finalized = false;
+    disabled = false;
+    lastSignature = "";
+    constructor(callbacks, opts = {}) {
+        this.callbacks = callbacks;
+        this.opts = opts;
+    }
+    get id() { return this.messageId; }
+    /** Begin the flow; schedules lazy card creation after delayMs. */
+    start() {
+        if (this.disabled || this.finalized || this.createTimer || this.messageId)
+            return;
+        this.startedAt = Date.now();
+        this.createTimer = setTimeout(() => {
+            this.createTimer = undefined;
+            this.createPromise = this.ensureCreated();
+        }, this.opts.delayMs ?? DEFAULT_DELAY_MS);
+        this.createTimer.unref?.();
+    }
+    /** Native compaction gave up (timeout/no-op); switch the card to fast-trim. */
+    async toToolTrim() {
+        if (this.finalized || this.phase === "tool-trim")
+            return;
+        this.phase = "tool-trim";
+        await this.refresh();
+    }
+    /** Finished successfully; patch the card to the done state with a detail line. */
+    async done(detail) {
+        await this.finish("done", detail);
+    }
+    /** Nothing to compact; patch the card to a neutral "no-op" state. */
+    async noop(detail) {
+        await this.finish("noop", detail);
+    }
+    /** Failed; patch the card to the failed state with an error detail line. */
+    async fail(detail) {
+        await this.finish("failed", detail);
+    }
+    /** Tear down timers without sending anything (e.g. on unexpected disposal). */
+    dispose() {
+        this.finalized = true;
+        this.stopTimers();
+    }
+    async finish(state, detail) {
+        if (this.finalized)
+            return;
+        this.state = state;
+        this.detail = detail;
+        this.finalized = true;
+        this.stopTimers();
+        // Wait for any in-flight lazy create so we can patch (not orphan) the card.
+        if (this.createPromise)
+            await this.createPromise.catch(() => { });
+        if (!this.messageId || this.disabled)
+            return;
+        await this.safeEdit(true);
+    }
+    async refresh() {
+        if (this.finalized || this.disabled)
+            return;
+        await this.ensureCreatedNow();
+        await this.safeEdit();
+    }
+    async ensureCreatedNow() {
+        if (this.createTimer) {
+            clearTimeout(this.createTimer);
+            this.createTimer = undefined;
+            this.createPromise = this.ensureCreated();
+        }
+        if (this.createPromise)
+            await this.createPromise.catch(() => { });
+    }
+    async ensureCreated() {
+        if (this.disabled || this.finalized || this.messageId)
+            return;
+        try {
+            const id = await this.callbacks.create(this.buildView());
+            if (!id) {
+                this.disabled = true;
+                return;
+            }
+            this.messageId = id;
+            this.lastSignature = this.signature();
+            this.startTicker();
+        }
+        catch (err) {
+            this.disabled = true;
+            this.callbacks.warn?.("compact progress create failed", err);
+        }
+    }
+    /** Refresh the elapsed-time footer periodically even with no phase change. */
+    startTicker() {
+        if (this.tickTimer || this.disabled || this.finalized)
+            return;
+        const tickMs = this.opts.tickMs ?? DEFAULT_TICK_MS;
+        this.tickTimer = setInterval(() => {
+            if (this.finalized || this.disabled || !this.messageId)
+                return;
+            void this.safeEdit();
+        }, tickMs);
+        this.tickTimer.unref?.();
+    }
+    async safeEdit(force = false) {
+        if (!this.messageId || this.disabled)
+            return;
+        if (!force && this.finalized)
+            return;
+        const sig = this.signature();
+        if (!force && sig === this.lastSignature)
+            return;
+        try {
+            await this.callbacks.edit(this.messageId, this.buildView());
+            this.lastSignature = sig;
+        }
+        catch (err) {
+            this.disabled = true;
+            this.stopTimers();
+            this.callbacks.warn?.("compact progress edit failed", err);
+        }
+    }
+    stopTimers() {
+        if (this.createTimer) {
+            clearTimeout(this.createTimer);
+            this.createTimer = undefined;
+        }
+        if (this.tickTimer) {
+            clearInterval(this.tickTimer);
+            this.tickTimer = undefined;
+        }
+    }
+    /** Dedupe key; includes elapsed so the ticking footer still advances. */
+    signature() {
+        return `${this.state}|${this.phase}|${this.formatElapsed()}|${this.detail || ""}`;
+    }
+    formatElapsed() {
+        const totalSec = Math.max(0, Math.floor((Date.now() - this.startedAt) / 1000));
+        const m = Math.floor(totalSec / 60);
+        const s = totalSec % 60;
+        return `${m}:${String(s).padStart(2, "0")}`;
+    }
+    buildView() {
+        return {
+            state: this.state,
+            phase: this.phase,
+            elapsed: this.formatElapsed(),
+            detail: this.detail,
+        };
+    }
+}

package/dist/feishu-bot.d.ts

@@ -34,6 +34,8 @@ export declare class FeishuBot {
     private delayedFailureTimers;
     /** Last time a real assistant-visible reply was successfully handed to the delivery pipeline. */
     private lastRealDeliveryAt;
+    /** Per-chat: whether we've already sent the high-context alert this cycle. */
+    private contextAlerted;
     /** Active chatSend trigger target so final replies and proactive session.message share one delivery key. */
     private activeDeliveryTargets;
     private adminOpenId;
@@ -117,6 +119,51 @@ export declare class FeishuBot {
     private isBridgeControlReply;
     private isLegacyBridgeControlMessage;
     private isRuntimeFailureText;
+    /**
+     * Is this main-run error worth auto-retrying (by resuming the session via the
+     * probe loop)? Mainly transient failures — request/response timeouts and
+     * aborted/incomplete runs. We do NOT auto-retry clearly terminal errors
+     * (auth/permission/quota/billing/model-not-supported), which would just fail
+     * again. The error text comes from collectReply's `Agent error: <msg>`.
+     */
+    private isRetryableAgentError;
+    /**
+     * Heuristic: does this reply look truncated / mid-task? Bias toward false
+     * positives (“宁可错杀不放过”) — a false positive only costs one invisible
+     * confirmation round, and the session self-check is the real arbiter. We gate
+     * only on cheap text shape here, never on stopReason (the upstream rarely
+     * provides one for normal-looking-but-truncated finals).
+     */
+    private looksTruncated;
+    /** Current context usage percent for a session (totalTokens / contextTokens),
+     *  or 0 if it cannot be determined. Same basis as /status. */
+    private getContextUsagePercent;
+    /**
+     * After a reply is delivered, alert the user once if context usage crossed the
+     * threshold (default 80%), so they can compact before a session bloats into the
+     * timeout/lock/overflow failure modes. We only alert on a fresh crossing: once
+     * alerted we stay quiet until usage drops back below the threshold (e.g. after
+     * a compact), then re-arm.
+     */
+    private maybeAlertHighContext;
+    /** True when the agent's reply is exactly a completion phrase (zh or en,
+     *  tolerant of trailing punctuation/whitespace and case). */
+    /**
+     * True when the agent's reply means “done”. We accept the exact phrase as well
+     * as common wrappers (“已经结束了” / “好的，结束了” / “yes, DONE”), but reject it
+     * when a negation/not-finished cue is present (“还没结束” / “not done”), so a
+     * “still working” answer never counts as completion.
+     */
+    private isDonePhrase;
+    /**
+     * Auto-retry loop: if `reply` looks truncated, ask the same session whether it
+     * finished. The session is the arbiter: if it replies exactly the done phrase,
+     * the ORIGINAL reply was the real result and we deliver that. Otherwise the
+     * session kept working and its new output becomes the latest reply, which we
+     * re-check. Loops until the session confirms completion, a reply no longer
+     * looks truncated, the budget is spent, or the session cannot answer.
+     */
+    private autoRetryUntilComplete;
     private cancelDelayedFailure;
     private setActiveDeliveryTarget;
     private scheduleDelayedFailure;
@@ -153,6 +200,14 @@ export declare class FeishuBot {
     private sendLiveStatusCard;
     private replyLiveStatusCard;
     private patchLiveStatusCard;
+    /**
+     * Render the /compact progress card. While running it shows a phase line plus a
+     * ticking elapsed footer so the user can see compaction is in progress; when
+     * terminal it collapses to a single compact line (success/skip/fail).
+     */
+    private buildCompactProgressCard;
+    private replyCompactCard;
+    private patchCompactCard;
     private sendTextMessage;
     private replyTextMessage;
     private editTextMessage;
@@ -202,6 +257,17 @@ export declare class FeishuBot {
     /**
      * Handle /compact command: compress session context.
      */
+    /**
+     * Compact a session with a fallback chain:
+     *   1. OpenClaw's native (LLM-summary) compaction — best semantics.
+     *   2. If that did not compact (or threw), fall back to "tool-trim": rewrite
+     *      the transcript file to drop tool calls/results while keeping the
+     *      conversation. This needs no model, so it works no matter how large the
+     *      session is (the native path itself fails to fit an oversized session
+     *      into the model). A backup is always written before any file change.
+     * Returns a structured result describing what happened.
+     */
+    private compactWithFallback;
     private handleCompactCommand;
     /**
      * Handle /reset command: fire sessions.reset and confirm.