openclaw-lark-multi-agent 1.3.0 → 1.4.2

package/README.md

@@ -70,9 +70,12 @@ After the package is published to npm:
 
 ```bash
 npm install -g openclaw-lark-multi-agent
-openclaw-lark-multi-agent init
+lma init
 ```
 
+> The command is `lma` (short). It is also available under its full name
+> `openclaw-lark-multi-agent` for back-compat.
+
 This creates:
 
 - config: `~/.openclaw/openclaw-lark-multi-agent/config.json`
@@ -81,29 +84,47 @@ This creates:
 Edit the generated config and fill in your OpenClaw Gateway token and Lark app credentials. Then run:
 
 ```bash
-openclaw-lark-multi-agent start
+lma start
 ```
 
 Install as a systemd user service:
 
 ```bash
-openclaw-lark-multi-agent install-systemd --user
+lma install-systemd --user
 ```
 
 On Windows, install [NSSM](https://nssm.cc/download), make sure `nssm.exe` is in `PATH`, then run PowerShell or Command Prompt as Administrator:
 
 ```powershell
-openclaw-lark-multi-agent install-windows-service
+lma install-windows-service
 ```
 
+### Optional: real-time steering plugin
+
+To let users nudge/correct a long-running agent turn in real time (instead of
+waiting for it to finish), install the bundled `lma-steer` OpenClaw plugin:
+
+```bash
+lma install-steer-plugin
+# then restart the OpenClaw gateway so it loads the plugin:
+systemctl --user restart openclaw-gateway.service
+```
+
+When the agent is mid-run and a new message arrives, the bridge injects it into
+the active run at the next tool-call boundary (Feishu shows the "Get" reaction).
+Without the plugin, the bridge falls back to queuing the message until the run
+finishes — everything still works, just without real-time steering. See
+`plugins/lma-steer/README.md` for details.
+
 Useful CLI commands:
 
 ```bash
-openclaw-lark-multi-agent --help
-openclaw-lark-multi-agent doctor
-openclaw-lark-multi-agent start [config]
-openclaw-lark-multi-agent init [--state-dir DIR] [--force]
-openclaw-lark-multi-agent install-systemd [--user|--system] [--state-dir DIR]
+lma --help
+lma doctor
+lma start [config]
+lma init [--state-dir DIR] [--force]
+lma install-systemd [--user|--system] [--state-dir DIR]
+lma install-steer-plugin [--no-force]
 ```
 
 ## Quick start from source
@@ -194,15 +215,15 @@ The npm CLI works on Windows as well. It uses `%USERPROFILE%\.openclaw\openclaw-
 
 ```powershell
 npm install -g openclaw-lark-multi-agent
-openclaw-lark-multi-agent init
+lma init
 notepad $env:USERPROFILE\.openclaw\openclaw-lark-multi-agent\config.json
-openclaw-lark-multi-agent start
+lma start
 ```
 
 To run as a Windows service, install [NSSM](https://nssm.cc/download), put `nssm.exe` in `PATH`, open an elevated terminal, then run:
 
 ```powershell
-openclaw-lark-multi-agent install-windows-service
+lma install-windows-service
 ```
 
 A legacy helper script is also available at `scripts/install-windows-service.bat`.

package/dist/cli.js

@@ -6,6 +6,11 @@ import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { startApp } from "./index.js";
 const APP_NAME = "openclaw-lark-multi-agent";
+// Short command name shown in help/usage. The published binary is available as
+// both `lma` (preferred) and `openclaw-lark-multi-agent` (back-compat). APP_NAME
+// stays as the long identifier for the state dir and systemd unit so existing
+// installs keep working; only the user-facing command label is shortened.
+const CLI_NAME = "lma";
 const HOME_DIR = homedir() || process.env.HOME || process.cwd();
 const DEFAULT_STATE_DIR = resolve(HOME_DIR, ".openclaw", APP_NAME);
 const DEFAULT_CONFIG_PATH = resolve(DEFAULT_STATE_DIR, "config.json");
@@ -13,18 +18,22 @@ function usage(exitCode = 0) {
     console.log(`OpenClaw Lark Multi-Agent
 
 Usage:
-  ${APP_NAME} start [config]
-  ${APP_NAME} init [--state-dir DIR] [--force]
-  ${APP_NAME} install-systemd [--user|--system] [--state-dir DIR] [--no-restart]
-  ${APP_NAME} install-windows-service [--state-dir DIR] [--no-start]
-  ${APP_NAME} doctor [--state-dir DIR]
-  ${APP_NAME} --help
+  ${CLI_NAME} start [config]
+  ${CLI_NAME} init [--state-dir DIR] [--force]
+  ${CLI_NAME} install-systemd [--user|--system] [--state-dir DIR] [--no-restart]
+  ${CLI_NAME} install-windows-service [--state-dir DIR] [--no-start]
+  ${CLI_NAME} install-steer-plugin [--no-force]
+  ${CLI_NAME} doctor [--state-dir DIR]
+  ${CLI_NAME} --help
 
 Examples:
-  ${APP_NAME} init
-  ${APP_NAME} start ~/.openclaw/${APP_NAME}/config.json
-  ${APP_NAME} install-systemd --user
-  ${APP_NAME} install-windows-service
+  ${CLI_NAME} init
+  ${CLI_NAME} start ~/.openclaw/${APP_NAME}/config.json
+  ${CLI_NAME} install-systemd --user
+  ${CLI_NAME} install-windows-service
+  ${CLI_NAME} install-steer-plugin
+
+(The command is also available as \`${APP_NAME}\` for back-compat.)
 `);
     process.exit(exitCode);
 }
@@ -114,7 +123,12 @@ WantedBy=${params.mode === "system" ? "multi-user.target" : "default.target"}
 `;
 }
 function run(cmd, args) {
-    execFileSync(cmd, args, { stdio: "inherit" });
+    // On Windows, npm-installed CLIs (like `openclaw`) are .cmd shims. Node's
+    // execFileSync does NOT resolve/execute .cmd files without shell:true (it
+    // fails with ENOENT before the subprocess ever starts — no output from the
+    // target command at all). Native .exe tools (nssm, systemctl on Linux) are
+    // unaffected by this flag either way, so enabling it only on win32 is safe.
+    execFileSync(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
 }
 function runSudo(args) {
     run("sudo", args);
@@ -172,6 +186,72 @@ function cmdInstallWindowsService(args) {
         run("nssm", ["start", APP_NAME]);
     console.log(`Installed Windows service: ${APP_NAME}`);
 }
+function runCapture(cmd, args) {
+    try {
+        // See run()'s comment: Windows needs shell:true to execute a .cmd shim
+        // (e.g. openclaw installed via `npm install -g`), otherwise the subprocess
+        // never starts (ENOENT) and no output from it is ever produced.
+        execFileSync(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+        return { code: 0 };
+    }
+    catch (err) {
+        const code = typeof err?.status === "number" ? err.status : 1;
+        // A spawn failure (command never started) has no numeric exit status/signal
+        // from the target process — surface that distinctly from "the command ran
+        // and returned non-zero", since the fix differs (PATH vs. the tool's own error).
+        const spawnError = typeof err?.status !== "number" && !err?.signal
+            ? (err?.message || String(err))
+            : undefined;
+        return { code, spawnError };
+    }
+}
+/**
+ * Install the bundled lma-steer OpenClaw plugin into the local OpenClaw gateway.
+ * The plugin registers the `lma.steer` gateway method that the bridge uses to
+ * inject a message into an active run at the next tool-call boundary. The plugin
+ * ships inside this package under plugins/lma-steer (built to dist).
+ */
+function cmdInstallSteerPlugin(args) {
+    // Default to --force so reinstalling an updated bundled plugin overwrites the
+    // previously installed copy. Pass --no-force to keep an existing install.
+    const noForce = hasFlag(args, "--no-force");
+    hasFlag(args, "--force");
+    if (args.length > 0)
+        throw new Error(`Unknown install-steer-plugin arguments: ${args.join(" ")}`);
+    // Resolve the bundled plugin dir relative to this CLI file: dist/cli.js -> ../plugins/lma-steer.
+    const cliDir = dirname(fileURLToPath(import.meta.url));
+    const pluginDir = resolve(cliDir, "..", "plugins", "lma-steer");
+    if (!existsSync(resolve(pluginDir, "openclaw.plugin.json")) || !existsSync(resolve(pluginDir, "dist", "index.js"))) {
+        throw new Error(`bundled lma-steer plugin not found or not built at: ${pluginDir}`);
+    }
+    const openclawBin = process.env.OPENCLAW_BIN || "openclaw";
+    const installArgs = ["plugins", "install", pluginDir];
+    if (!noForce)
+        installArgs.push("--force");
+    console.log(`Installing lma-steer plugin from: ${pluginDir}`);
+    const res = runCapture(openclawBin, installArgs);
+    if (res.code !== 0) {
+        if (res.spawnError) {
+            // The subprocess never started (e.g. Windows failing to exec a .cmd shim
+            // without a shell, or the binary truly missing from PATH). This is
+            // distinct from "openclaw ran and returned an error" — no output above
+            // this line came from openclaw itself.
+            console.error(`\nCould not start "${openclawBin}": ${res.spawnError}`);
+            console.error(`Make sure the OpenClaw CLI is installed and on PATH (or set OPENCLAW_BIN to its full path),`);
+        }
+        else {
+            console.error(`\n"${openclawBin} plugins install" failed (exit ${res.code}).`);
+            console.error(`Make sure the OpenClaw CLI is installed and on PATH (or set OPENCLAW_BIN),`);
+        }
+        console.error(`then rerun: ${CLI_NAME} install-steer-plugin`);
+        process.exit(res.code);
+    }
+    console.log(`\nlma-steer plugin installed. Restart the OpenClaw gateway to load it, e.g.:`);
+    console.log(`  systemctl --user restart openclaw-gateway.service`);
+    console.log(`Then verify:`);
+    console.log(`  openclaw gateway call lma.steer --params '{"sessionKey":"test","text":"ping"}'`);
+    console.log(`  (expect {"status":"no_active_run"} for an idle session)`);
+}
 function cmdDoctor(args) {
     const stateDir = resolve(takeOption(args, "--state-dir") || DEFAULT_STATE_DIR);
     if (args.length > 0)
@@ -194,6 +274,8 @@ async function main() {
         return cmdInstallSystemd(args);
     if (cmd === "install-windows-service")
         return cmdInstallWindowsService(args);
+    if (cmd === "install-steer-plugin")
+        return cmdInstallSteerPlugin(args);
     if (cmd === "doctor")
         return cmdDoctor(args);
     if (cmd === "start") {

package/dist/feishu-bot.js

@@ -29,6 +29,17 @@ function autoRetryMax() { return Number(process.env.OPENCLAW_LARK_MULTI_AGENT_AU
 // for the locale-appropriate phrase; detection accepts BOTH so either works.
 const AUTO_RETRY_DONE_PHRASE = process.env.OPENCLAW_LARK_MULTI_AGENT_AUTO_RETRY_DONE_PHRASE || "\u7ed3\u675f\u4e86";
 const AUTO_RETRY_DONE_PHRASE_EN = process.env.OPENCLAW_LARK_MULTI_AGENT_AUTO_RETRY_DONE_PHRASE_EN || "DONE";
+// Prefix wrapped around a steered (mid-run inserted) message so the agent knows
+// it is a NEW user message that arrived while it was still working, and should
+// be handled together with the current task. The live-status card and reactions
+// still key off the ORIGINAL text; only what OpenClaw receives is wrapped.
+function steerInjectionPrefix(en) {
+    const zh = process.env.OPENCLAW_LARK_MULTI_AGENT_STEER_PREFIX
+        || "【用户中途插入的新消息，请与当前任务一起处理】";
+    const enText = process.env.OPENCLAW_LARK_MULTI_AGENT_STEER_PREFIX_EN
+        || "[New message inserted by the user mid-task; please handle it together with the current task]";
+    return en ? enText : zh;
+}
 // How many of the most-recent tool calls (and their results) tool-trim keeps
 // intact — recent tool calls may still be relevant to the agent's next step.
 function toolTrimKeepRecent() { return Number(process.env.OPENCLAW_LARK_MULTI_AGENT_TOOLTRIM_KEEP_RECENT || 3); }
@@ -900,15 +911,35 @@ export class FeishuBot {
                 // seen at the next tool-call boundary (lets the user nudge/correct a long
                 // run in real time). The lma-steer plugin reports whether it landed.
                 const sessionKeyForSteer = this.getSessionKey(chatId);
-                const steer = await this.openclawClient.steer(sessionKeyForSteer, cleanText).catch(() => ({ status: "unavailable" }));
+                // Wrap the message so the agent knows it is a NEW user message inserted
+                // mid-task. The live-status line and reactions still key off the original.
+                const steerWrapped = `${steerInjectionPrefix(this.isEn(chatId))}\n${cleanText}`;
+                const steer = await this.openclawClient.steer(sessionKeyForSteer, steerWrapped, cleanText).catch(() => ({ status: "unavailable" }));
                 if (steer.status === "steered") {
-                    // Inserted into the active run. Reuse the existing reaction lifecycle:
-                    // mark "Get" (received/inserted); the current run's completion will
-                    // advance it to DONE together with the rest of the batch.
-                    await this.addReaction(messageId, "Get").catch(() => { });
-                    pending.push({ messageId, emoji: "Get", rowId: insertedId });
+                    // Accepted into the active run's steer queue, but NOT yet consumed by
+                    // the model. Show "Typing" (awaiting insertion) now; flip to "Get" only
+                    // when the model actually consumes it at a tool-call boundary (a
+                    // matching sessionUser event), which also renders it on the live-status
+                    // card in correct time order.
+                    await this.addReaction(messageId, "Typing").catch(() => { });
+                    pending.push({ messageId, emoji: "Typing", rowId: insertedId });
                     this.pendingAckMessages.set(chatId, pending);
-                    console.log(`[${this.config.name}] Agent busy for ${chatId.slice(-8)}, STEERED into active run: "${cleanText.substring(0, 50)}..."`);
+                    const norm = cleanText.replace(/\s+/g, " ").trim();
+                    this.openclawClient.onSteerConsumed(sessionKeyForSteer, (consumedText) => {
+                        const cn = (consumedText || "").replace(/\s+/g, " ").trim();
+                        if (cn !== norm && !cn.includes(norm))
+                            return false; // not ours; keep waiting
+                        // Flip Typing -> Get now that the model has actually read it.
+                        void this.removeReaction(messageId, "Typing").catch(() => { });
+                        void this.addReaction(messageId, "Get").catch(() => { });
+                        const acks = this.pendingAckMessages.get(chatId) || [];
+                        for (const a of acks)
+                            if (a.messageId === messageId)
+                                a.emoji = "Get";
+                        this.pendingAckMessages.set(chatId, acks);
+                        return true; // one-shot: matched, remove this callback
+                    });
+                    console.log(`[${this.config.name}] Agent busy for ${chatId.slice(-8)}, STEERED (awaiting consumption): "${cleanText.substring(0, 50)}..."`);
                     // The message is already in DB with a pending trigger. Clear that
                     // trigger so it is NOT re-run as a separate follow-up batch after the
                     // current run ends — it has already been injected into this run.
@@ -2247,7 +2278,8 @@ export class FeishuBot {
                 : kind === "tool_end" ? "✓"
                     : kind === "lifecycle" ? "⋯"
                         : kind === "summary" ? "📊"
-                            : "•";
+                            : kind === "steer" ? "💬"
+                                : "•";
             const fmtAt = (sec) => `${Math.floor(sec / 60)}:${String(sec % 60).padStart(2, "0")}`;
             const content = view.lines
                 .map((l) => {

package/dist/live-status.d.ts

@@ -1,7 +1,7 @@
 import type { ProgressEvent } from "./openclaw-client";
 /** One activity line shown in the card content area. */
 export type LiveStatusLine = {
-    kind: "tool_start" | "tool_end" | "text" | "lifecycle" | "summary";
+    kind: "tool_start" | "tool_end" | "text" | "lifecycle" | "summary" | "steer";
     text: string;
     /** Relative time (seconds since run start) when this line was produced. */
     at: number;

package/dist/live-status.js

@@ -83,6 +83,16 @@ export class LiveStatusController {
                 return;
             this.appendText(t);
         }
+        else if (event.kind === "steer") {
+            // A user message that was steered into THIS run and has now actually been
+            // consumed by the model at a tool-call boundary. It is appended as its own
+            // line so it lands in the correct time-order position (right after the
+            // tool that just finished), not merged with assistant text.
+            const t = (event.text || "").trim();
+            if (!t)
+                return;
+            this.pushLine("steer", t);
+        }
         else {
             return; // lifecycle ticks: ignore (footer timer already advances)
         }

package/dist/openclaw-client.d.ts

@@ -8,6 +8,9 @@ export type ProgressEvent = {
 } | {
     kind: "assistant_note";
     text: string;
+} | {
+    kind: "steer";
+    text: string;
 } | {
     kind: "lifecycle";
     text: string;
@@ -39,6 +42,10 @@ export declare class OpenClawClient {
     private lastToolNamesByItemId;
     private sessionMessageCallbacks;
     private progressCallbacks;
+    /** Per-session steered messages awaiting consumption confirmation. Maps the
+     *  normalized text actually sent (possibly wrapped with an insertion prefix)
+     *  to the ORIGINAL display text shown on the live-status card. */
+    private pendingSteerTexts;
     /** Sessions where verbose mode should deliver visible transcript text even when mixed with tool blocks. */
     private verboseTranscriptSessions;
     private verboseAssistantTimers;
@@ -129,10 +136,30 @@ export declare class OpenClawClient {
      *  - "unavailable"   -> the lma-steer plugin/method is not available (e.g. not
      *                       installed or gateway not restarted); caller falls back.
      */
-    steer(sessionKey: string, text: string): Promise<{
+    steer(sessionKey: string, text: string, displayText?: string): Promise<{
         status: "steered" | "no_active_run" | "rejected" | "unavailable";
         sessionId?: string;
     }>;
+    /** Callbacks fired when a steered message is confirmed consumed by the model
+     *  (matching sessionUser event). Keyed by bare/short session key. Multiple may
+     *  be registered when several messages are steered during one run; each is
+     *  invoked with the consumed text and decides whether it is the one it wants.
+     *  Callbacks are one-shot: returning true removes them. */
+    private steerConsumedCallbacks;
+    /** Register a callback (per bare session key) invoked when a steered message
+     *  is actually consumed by the active run. The bridge uses this to flip the
+     *  Feishu reaction from "Typing" (awaiting insertion) to "Get" (inserted).
+     *  Return true from the callback to consume/remove it (one-shot). */
+    onSteerConsumed(sessionKey: string, cb: (text: string) => boolean | void): void;
+    private shortKey;
+    private registerPendingSteer;
+    /**
+     * Called when a sessionUser event is seen for a session. If its text matches a
+     * pending steered message, fire the live-status `steer` line (correct time
+     * order, showing the ORIGINAL text) and the steer-consumed callback, then
+     * clear that pending entry. Returns true if it matched a steered message.
+     */
+    private handleSteerConsumption;
     /**
      * Get session info (model, tokens, etc.) for status display.
      */

package/dist/openclaw-client.js

@@ -30,6 +30,10 @@ export class OpenClawClient {
     lastToolNamesByItemId = new Map();
     sessionMessageCallbacks = new Map();
     progressCallbacks = new Map();
+    /** Per-session steered messages awaiting consumption confirmation. Maps the
+     *  normalized text actually sent (possibly wrapped with an insertion prefix)
+     *  to the ORIGINAL display text shown on the live-status card. */
+    pendingSteerTexts = new Map();
     /** Sessions where verbose mode should deliver visible transcript text even when mixed with tool blocks. */
     verboseTranscriptSessions = new Set();
     verboseAssistantTimers = new Map();
@@ -211,6 +215,11 @@ export class OpenClawClient {
                             stream: "sessionUser",
                             data: { text: visibleUserText },
                         });
+                        // If this user message is one we steered into the run, the model has
+                        // now actually consumed it (session.message is emitted as the message
+                        // is committed to the transcript). Render it on the live-status card
+                        // in correct time order and flip the reaction to Get.
+                        this.handleSteerConsumption(rawKey, visibleUserText);
                     }
                     const visibleAssistantText = this.extractVisibleAssistantText(msg);
                     if (visibleAssistantText) {
@@ -287,6 +296,21 @@ export class OpenClawClient {
                 this.connected = false;
                 this.connectPromise = null;
                 console.log("[OpenClaw] WS disconnected");
+                // Reject all in-flight RPCs so callers fail fast instead of hanging until
+                // their timeout. Combined with the collectReply disconnect check, this
+                // lets the bridge release busy locks promptly on a gateway restart.
+                if (this.pending.size > 0) {
+                    const err = new Error("Gateway disconnected");
+                    for (const [id, entry] of this.pending) {
+                        if (entry.timer)
+                            clearTimeout(entry.timer);
+                        try {
+                            entry.reject(err);
+                        }
+                        catch { /* ignore */ }
+                        this.pending.delete(id);
+                    }
+                }
                 if (this.shouldReconnect) {
                     this.scheduleReconnect();
                 }
@@ -489,6 +513,11 @@ export class OpenClawClient {
      */
     collectReply(runId, timeoutMs = 1800000, targetSessionKey, options) {
         return new Promise((resolve, reject) => {
+            // Whether we were connected when the run started. We only treat a later
+            // disconnect as a mid-run gateway drop (fail fast) if we began connected;
+            // this keeps unit tests that drive collectReply without a live socket from
+            // tripping the disconnect path.
+            const startedConnected = this.connected;
             let text = "";
             let chatDeltaText = "";
             let chatFinalText = "";
@@ -607,6 +636,28 @@ export class OpenClawClient {
                 resolve(finalText);
             };
             const poller = setInterval(() => {
+                // Gateway connection dropped mid-run (e.g. gateway restart): the run will
+                // never deliver a reply on this connection, so stop waiting instead of
+                // hanging until the 30-min idle timeout. Failing fast lets the bridge
+                // release its busy lock so new messages are not stuck "waiting".
+                if (startedConnected && !this.connected) {
+                    clearInterval(poller);
+                    if (chatFinalTimer)
+                        clearTimeout(chatFinalTimer);
+                    if (lifecycleEndTimer)
+                        clearTimeout(lifecycleEndTimer);
+                    if (replayInvalidTimer)
+                        clearTimeout(replayInvalidTimer);
+                    if (idleTimer)
+                        clearTimeout(idleTimer);
+                    const salvaged = this.pickBestCollectedText(chatFinalText, text, chatDeltaText, transcriptAssistantText);
+                    if (salvaged) {
+                        resolve(salvaged);
+                        return;
+                    }
+                    reject(new Error("Gateway disconnected during run"));
+                    return;
+                }
                 // /stop force-abort: finish immediately instead of waiting for the
                 // cancelled lifecycle to be treated as a transient state (idle timeout).
                 if (sessionKey && (this.forceAbortedSessions.has(sessionKey) || this.forceAbortedSessions.has(shortSessionKey))) {
@@ -933,11 +984,18 @@ export class OpenClawClient {
      *  - "unavailable"   -> the lma-steer plugin/method is not available (e.g. not
      *                       installed or gateway not restarted); caller falls back.
      */
-    async steer(sessionKey, text) {
+    async steer(sessionKey, text, displayText) {
         try {
             const res = await this.rpc("lma.steer", { sessionKey, text }, 10000);
             const status = res?.status;
             if (status === "steered" || status === "no_active_run" || status === "rejected") {
+                // On a successful steer, remember the text so that when the model
+                // actually consumes it (a matching sessionUser event on THIS run) we can
+                // render it on the live-status card in correct time order and let the
+                // bridge flip the reaction to Get only after real consumption. Match on
+                // the (possibly wrapped) text actually sent; display the original.
+                if (status === "steered")
+                    this.registerPendingSteer(sessionKey, text, displayText);
                 return { status, sessionId: typeof res?.sessionId === "string" ? res.sessionId : undefined };
             }
             return { status: "unavailable" };
@@ -952,6 +1010,90 @@ export class OpenClawClient {
             return { status: "unavailable" };
         }
     }
+    /** Callbacks fired when a steered message is confirmed consumed by the model
+     *  (matching sessionUser event). Keyed by bare/short session key. Multiple may
+     *  be registered when several messages are steered during one run; each is
+     *  invoked with the consumed text and decides whether it is the one it wants.
+     *  Callbacks are one-shot: returning true removes them. */
+    steerConsumedCallbacks = new Map();
+    /** Register a callback (per bare session key) invoked when a steered message
+     *  is actually consumed by the active run. The bridge uses this to flip the
+     *  Feishu reaction from "Typing" (awaiting insertion) to "Get" (inserted).
+     *  Return true from the callback to consume/remove it (one-shot). */
+    onSteerConsumed(sessionKey, cb) {
+        const key = this.shortKey(sessionKey);
+        let list = this.steerConsumedCallbacks.get(key);
+        if (!list) {
+            list = [];
+            this.steerConsumedCallbacks.set(key, list);
+        }
+        list.push(cb);
+    }
+    shortKey(sessionKey) {
+        return sessionKey.replace(/^agent:[^:]+:/, "");
+    }
+    registerPendingSteer(sessionKey, text, displayText) {
+        const key = this.shortKey(sessionKey);
+        const norm = text.replace(/\s+/g, " ").trim();
+        if (!norm)
+            return;
+        let map = this.pendingSteerTexts.get(key);
+        if (!map) {
+            map = new Map();
+            this.pendingSteerTexts.set(key, map);
+        }
+        map.set(norm, (displayText || text).trim());
+    }
+    /**
+     * Called when a sessionUser event is seen for a session. If its text matches a
+     * pending steered message, fire the live-status `steer` line (correct time
+     * order, showing the ORIGINAL text) and the steer-consumed callback, then
+     * clear that pending entry. Returns true if it matched a steered message.
+     */
+    handleSteerConsumption(sessionKey, text) {
+        const key = this.shortKey(sessionKey);
+        const map = this.pendingSteerTexts.get(key);
+        if (!map || map.size === 0)
+            return false;
+        const norm = (text || "").replace(/\s+/g, " ").trim();
+        if (!norm)
+            return false;
+        // Match exact, or the sessionUser text containing the steered text (the run
+        // may wrap it). Prefer the longest matching pending entry.
+        let matched;
+        for (const pending of map.keys()) {
+            if (norm === pending || norm.includes(pending)) {
+                if (!matched || pending.length > matched.length)
+                    matched = pending;
+            }
+        }
+        if (!matched)
+            return false;
+        const display = map.get(matched) || matched;
+        map.delete(matched);
+        if (map.size === 0)
+            this.pendingSteerTexts.delete(key);
+        const progressCb = this.progressCallbacks.get(key) || this.progressCallbacks.get(`agent:main:${key}`);
+        if (progressCb)
+            void progressCb({ kind: "steer", text: display });
+        const list = this.steerConsumedCallbacks.get(key);
+        if (list && list.length > 0) {
+            // Invoke callbacks; a callback returning true is one-shot and removed.
+            const remaining = list.filter((cb) => {
+                try {
+                    return cb(matched) !== true;
+                }
+                catch {
+                    return true;
+                }
+            });
+            if (remaining.length > 0)
+                this.steerConsumedCallbacks.set(key, remaining);
+            else
+                this.steerConsumedCallbacks.delete(key);
+        }
+        return true;
+    }
     /**
      * Get session info (model, tokens, etc.) for status display.
      */

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "openclaw-lark-multi-agent",
-  "version": "1.3.0",
+  "version": "1.4.2",
   "description": "Multi-bot Lark/Feishu bridge for OpenClaw, with per-bot model routing and isolated sessions",
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run build:steer-plugin",
+    "build:steer-plugin": "tsc -p plugins/lma-steer/tsconfig.json",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
@@ -22,6 +23,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.5",
+    "openclaw": "^2026.6.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.5"
@@ -45,11 +47,16 @@
     "gateway"
   ],
   "bin": {
+    "lma": "dist/cli.js",
     "openclaw-lark-multi-agent": "dist/cli.js"
   },
   "files": [
     "dist",
     "scripts",
+    "plugins/lma-steer/dist",
+    "plugins/lma-steer/openclaw.plugin.json",
+    "plugins/lma-steer/package.json",
+    "plugins/lma-steer/README.md",
     "config.example.json",
     "README.md",
     "README.zh-CN.md",

package/plugins/lma-steer/README.md

@@ -0,0 +1,45 @@
+# lma-steer
+
+An OpenClaw plugin bundled with **openclaw-lark-multi-agent**. It registers a
+Gateway method `lma.steer` that the bridge uses to inject a message into an
+**active** OpenClaw run at the next tool-call boundary — so a user can nudge or
+correct a long-running task in real time instead of waiting for it to finish.
+
+## Why a plugin
+
+Native `chat.send` with `queue.mode=steer` only acks `{status:"started"}` — it
+cannot tell the bridge whether the message actually steered into the active run,
+was queued as a followup, or was rejected. This plugin uses the runtime
+primitives `resolveActiveEmbeddedRunSessionId` + `queueAgentHarnessMessage`,
+which expose that distinction, so the bridge can render an accurate Feishu
+reaction.
+
+## Install
+
+From an installed `openclaw-lark-multi-agent`:
+
+```bash
+openclaw-lark-multi-agent install-steer-plugin
+```
+
+Then restart the OpenClaw gateway so it loads the plugin:
+
+```bash
+systemctl --user restart openclaw-gateway.service
+```
+
+Verify (an idle session returns `no_active_run`):
+
+```bash
+openclaw gateway call lma.steer --params '{"sessionKey":"test","text":"ping"}'
+```
+
+## Gateway method
+
+`lma.steer`
+
+- params: `{ sessionKey: string, text: string }`
+- result: `{ status: "steered" | "no_active_run" | "rejected", sessionId?: string }`
+  - `steered` — queued into the active run; seen at the next tool-call boundary
+  - `no_active_run` — no active run; caller should send as a normal new message
+  - `rejected` — active run refused the injection (e.g. compacting / not streaming)

package/plugins/lma-steer/dist/index.js

@@ -0,0 +1,100 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { resolveActiveEmbeddedRunSessionId, queueAgentHarnessMessage, } from "openclaw/plugin-sdk/agent-harness-runtime";
+const ERR_INVALID = "INVALID_REQUEST";
+// A run can be accepted but not yet resolvable/streaming (cold-start window).
+// Wait up to STEER_WAIT_MS (polling every STEER_POLL_MS) for it to become
+// steerable before falling back to no_active_run. Env-tunable.
+const STEER_WAIT_MS = Number(process.env.LMA_STEER_WAIT_MS || 8000);
+const STEER_POLL_MS = Number(process.env.LMA_STEER_POLL_MS || 300);
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/**
+ * Candidate session keys to try, in order. OpenClaw registers active runs under
+ * the fully-qualified key `agent:<agentId>:<key>` (e.g. agent:main:lma-claude-
+ * oc_xxx), but callers such as the LMA bridge pass the bare key (lma-claude-
+ * oc_xxx). Try the key as given first, then the agent:main:-qualified form, so
+ * both conventions resolve to the same active run.
+ */
+function sessionKeyCandidates(sessionKey) {
+    const out = [sessionKey];
+    if (!/^agent:/.test(sessionKey))
+        out.push(`agent:main:${sessionKey}`);
+    return out;
+}
+function resolveActiveSessionId(sessionKey) {
+    for (const key of sessionKeyCandidates(sessionKey)) {
+        const sessionId = resolveActiveEmbeddedRunSessionId(key);
+        if (sessionId)
+            return { sessionId, resolvedKey: key };
+    }
+    return {};
+}
+export default definePluginEntry({
+    id: "lma-steer",
+    name: "LMA Steer",
+    description: "Steer a queued message into the active OpenClaw run at the next tool-call boundary, with an observable outcome for the LMA bridge.",
+    register(api) {
+        api.registerGatewayMethod("lma.steer", async ({ params, respond }) => {
+            const sessionKey = readString(params.sessionKey);
+            const text = readString(params.text);
+            if (!sessionKey) {
+                respond(false, undefined, { code: ERR_INVALID, message: "lma.steer requires a non-empty sessionKey" });
+                return;
+            }
+            if (!text) {
+                respond(false, undefined, { code: ERR_INVALID, message: "lma.steer requires a non-empty text" });
+                return;
+            }
+            try {
+                // A run may be accepted (chat.send returned a runId) but still in its
+                // cold-start/queued window where it is not yet resolvable or streaming.
+                // The LMA bridge only calls steer when it believes a run is active, so
+                // briefly wait for the run to become steerable instead of giving up on
+                // the first miss. Total wait is bounded so we never hang the caller.
+                // We also try both the bare and agent:main:-qualified session key, since
+                // the bridge passes the bare key while runs register under the qualified one.
+                const deadline = Date.now() + STEER_WAIT_MS;
+                let { sessionId, resolvedKey } = resolveActiveSessionId(sessionKey);
+                let waited = 0;
+                while (!sessionId && Date.now() < deadline) {
+                    await sleep(STEER_POLL_MS);
+                    waited += STEER_POLL_MS;
+                    ({ sessionId, resolvedKey } = resolveActiveSessionId(sessionKey));
+                }
+                if (!sessionId) {
+                    console.log(`[lma-steer] no_active_run for ${sessionKey} after ${waited}ms wait`);
+                    const result = { status: "no_active_run" };
+                    respond(true, result);
+                    return;
+                }
+                // Queue the message into the active run. queueAgentHarnessMessage only
+                // succeeds once the run is actually streaming; if the run resolved but is
+                // not streaming yet, retry within the remaining budget.
+                let queued = queueAgentHarnessMessage(sessionId, text, { steeringMode: "all" });
+                while (!queued && Date.now() < deadline) {
+                    await sleep(STEER_POLL_MS);
+                    waited += STEER_POLL_MS;
+                    const re = resolveActiveSessionId(sessionKey);
+                    sessionId = re.sessionId || sessionId;
+                    queued = queueAgentHarnessMessage(sessionId, text, { steeringMode: "all" });
+                }
+                console.log(`[lma-steer] ${queued ? "steered" : "rejected"} ${sessionKey} (resolved=${resolvedKey}) sid=${sessionId} after ${waited}ms`);
+                const result = {
+                    status: queued ? "steered" : "rejected",
+                    sessionId,
+                };
+                respond(true, result);
+            }
+            catch (err) {
+                respond(false, undefined, {
+                    code: "INTERNAL",
+                    message: `lma.steer failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        });
+    },
+});

package/plugins/lma-steer/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "lma-steer",
+  "name": "LMA Steer",
+  "description": "Inject (steer) a queued user message into the active OpenClaw run at the next tool-call boundary, with an observable outcome the LMA bridge can render as a Feishu reaction.",
+  "version": "0.1.0",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/plugins/lma-steer/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "lma-steer",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "description": "OpenClaw plugin: steer a queued message into the active run at the next tool-call boundary (used by the LMA bridge).",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": ["./dist/index.js"],
+    "compat": {
+      "pluginApi": ">=2026.3.0"
+    }
+  }
+}