lark-remote 0.5.18 → 0.5.20

package/dist/bridge/index.d.ts

@@ -1,11 +1,12 @@
-import type { AgentRunner } from '../runner/index.js';
+import type { Runner, AgentRunner } from '../runner/index.js';
 import type { AgentRegistry } from '../runner/registry.js';
 import type { SessionReaderRegistry, SessionStore } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
-import { type RunCardChannel } from '../card/run-card-session.js';
-import { type RunTerminal } from '../card/run-state.js';
+import { RunCardSession, type RunCardChannel } from '../card/run-card-session.js';
+import { type RunCardRenderOptions } from '../card/run-renderer.js';
+import { type RunState, type RunTerminal } from '../card/run-state.js';
 import type { AgentKind } from '../agent-kinds.js';
-import { type StopOutcome } from '../runner/types.js';
+import type { StopOutcome } from '../runner/types.js';
 import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding, type ExecutingInfo } from './queue-manager.js';
 import type { InboundMediaPayload } from '../connector/index.js';
 import type { MediaOutcome } from '../inbound/turn.js';
@@ -29,6 +30,23 @@ export interface BridgeChannel extends RunCardChannel {
     addReaction(messageId: string, emoji: string): Promise<void>;
     removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
 }
+/**
+ * 终态卡的渲染快照：run 结束后唯一还能改这张卡的地方。
+ *
+ * 后台任务的生命周期跨 turn，卡片收尾只是"这一轮的投影结束了"，任务本身还在
+ * 跑；订阅拿到新名单后必须按 runId 找回同一张卡（state + 渲染选项 + 消息 id）。
+ */
+export interface RunCardSnapshot {
+    state: RunState;
+    options: RunCardRenderOptions;
+    cwd: string;
+    agentKind: AgentKind;
+    /**
+     * 这张终态卡的消息 id。缺失（流式卡没建起来、走了兜底纯发送）时后台任务
+     * 订阅无法落地——宁可退化成收尾快照，也不能凭空补发一张新卡。
+     */
+    messageId?: string;
+}
 /** Caller context shared by bridge operations and router command handling. */
 export interface CommandContext {
     userId: string;
@@ -95,6 +113,42 @@ interface BridgeDeps {
      */
     sessionReaderRegistry: SessionReaderRegistry;
 }
+export interface ActiveRun {
+    runId: string;
+    userId: string;
+    chatId: string;
+    session: RunCardSession;
+    cwd: string;
+    /**
+     * The exact runner instance that is running this run. interruptCurrentRun
+     * stops THIS instance directly rather than re-resolving via getRunner(cwd),
+     * so the runner is reachable even after clearRunners() empties the cache
+     * mid-run (a fresh empty runner's stop() was a no-op,
+     * leaving the real subprocess alive and the queue chain blocked forever).
+     */
+    runner: Runner;
+    /**
+     * The agent kind that this run started with. The runner cache is keyed by
+     * (cwd, agentKind); eviction must use THIS kind, not `this.config.defaultAgent`
+     * at eviction time. Otherwise switching defaultAgent mid-run
+     * (via `/config`, whose clearRunners skips the active cwd) makes finalizeRun
+     * delete the wrong slot — the original agent's runner lingers in the cache
+     * with a stale config snapshot.
+     */
+    agentKind: AgentKind;
+    /**
+     * Session id this run actually used (from system.init / turn_started).
+     * Immutable run identity for final usage: a mid-run /new //resume //cd moves
+     * the global session pointer, so reading `sessionStore.getSessionId()` at the
+     * end attributes another session's tokens to this run.
+     */
+    sessionId?: string;
+}
+/** `startIdleWatchdog` 的句柄：事件到达时 `touch()`，流结束/收尾时 `stop()`。 */
+export interface IdleWatchdog {
+    touch(): void;
+    stop(): void;
+}
 /**
  * Bridge owns the per-workspace serial processing queue (§9.6) and the
  * single-card streaming forwarding loop (§9.12 watchdog + session sync).
@@ -129,7 +183,7 @@ export declare class Bridge {
     private readonly mediaHandler;
     /**
      * Per-workspace runner instances, keyed by (cwd, agentKind).
-     * Fix 4 (2026-07-18): Each agentKind has its own cache slot, so switching
+     * Each agentKind has its own cache slot, so switching
      * defaultAgent creates a NEW runner without evicting the old one. This
      * eliminates the need for clearRunners() on agent switch, preventing the
      * regression where clearRunners() orphaned a running subprocess and
@@ -153,16 +207,11 @@ export declare class Bridge {
     /** 审批卡动作的实现（只读上面那张表；见 approval-actions.ts）。 */
     private approvalActions;
     /**
-     * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
-     * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
-     * 需要它反查 sessionId + agentKind。
-     *
-     * 为什么按 runId 存而不是「每 cwd 只留最新一条」：compact 卡片动作走串行
-     * 队列（会被正在跑的 run 挡住），点击到执行之间可能夹着别的 run 收尾。
-     * 单槽会被覆盖 —— 旧卡片的压缩必然报「该任务已结束或不属于当前会话」，
-     * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
+     * Compact 生命周期（见 compact.ts）：可压缩 run 记账、终态卡 / resume 卡
+     * 两条 Compact 入口、kimi 在途检测与压缩流式卡。activeRuns 槽位表按引用
+     * 共用——压缩注册前确认槽位空闲，否则 /stop 停错对象。
      */
-    private compactableRuns;
+    private readonly compact;
     /**
      * 终态卡片的渲染快照（runId → state + options）：run 结束后 activeRuns 已
      * 清空，而卡片上的「⏹ 停止」后台任务按钮（job.kill）还活着，需要按 runId
@@ -173,17 +222,22 @@ export declare class Bridge {
     private runCardSnapshots;
     private static readonly RUN_CARD_SNAPSHOT_MAX;
     /**
-     * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
-     * queue and may run in parallel with claude runs / other bash runs in the same
-     * cwd, so they live outside `activeRuns`. Tracked so `/stop` can reach
-     * the per-run BashRunner instance via interruptCurrentRun.
+     * 终态卡后台任务订阅与停止（见 job-watch.ts）：job.kill、名单订阅与
+     * PATCH 串行链收在该模块；jobCardPatches 链内渲染读 snapshot.state，
+     * 「停止」与「订阅帧」并发不会把卡片写回旧内容。
      */
-    private activeBashRuns;
+    private readonly jobWatch;
+    /**
+     * `!` bash 命令执行（见 bash-run.ts）：独立 runId 空间、独立登记表，不进
+     * activeRuns；绝不 re-chain 到 QueueManager（会自等待死锁）。/stop 的 bash
+     * 侧匹配与中断也收在该模块，避免误杀并行跑的 `!` 任务。
+     */
+    private readonly bashRuns;
     constructor(deps: BridgeDeps);
     /**
      * Get or create a runner for the given cwd, keyed by current defaultAgent.
      *
-     * Fix 4 (2026-07-18): Cache key includes agentKind, so switching defaultAgent
+     * Cache key includes agentKind, so switching defaultAgent
      * creates a NEW runner under a different key without evicting the old one.
      * This eliminates the need for clearRunners() on agent switch.
      */
@@ -340,14 +394,6 @@ export declare class Bridge {
         terminal: RunTerminal;
         command: string;
     }>;
-    interruptCurrentRun(input: {
-        userId: string;
-        chatId: string;
-        runId?: string;
-        /** Restrict the match to a single cwd (queue.immediate). When
-         * omitted, all workspaces are candidates (used by /stop, /t, and card stop button which don't know which cwd to target). */
-        cwd?: string;
-    }): Promise<boolean>;
     /**
      * Same as {@link interruptCurrentRun}, plus what the runner's stop actually
      * achieved. DSH returns a {@link StopOutcome} (withdrawn / cancelled /
@@ -360,8 +406,20 @@ export declare class Bridge {
         userId: string;
         chatId: string;
         runId?: string;
+        /**
+         * Card callback's server-provided message id. Used only as a narrow fallback
+         * when the behavior-value runId is missing or stale: the clicked card must
+         * be the one active run's card. A dashboard or historical card never matches.
+         */
+        cardMessageId?: string;
         cwd?: string;
     }): Promise<InterruptOutcome>;
+    /**
+     * Resolve a scoped card click by card identity. Empty input or multiple
+     * matches fail closed; production message ids are unique, but refusing an
+     * ambiguous stop is safer than killing several workspaces.
+     */
+    private activeRunsForCard;
     /**
      * 停掉一条已注册的 active run：置终态、停 runner、摘槽位、标 stale、
      * 归零该 cwd 的队列执行计数。返回 runner 的停止结果（DSH 才有）。
@@ -370,15 +428,22 @@ export declare class Bridge {
      * 出现「停第一条就 return」的漏停。
      */
     private interruptActiveRun;
-    /** Send a result message to the user (§7). Returns true on success, false on failure. */
-    sendResult(result: CommandResult, ctx: CommandContext): Promise<boolean>;
+    /**
+     * Send a result message to the user (§7). Returns true on success, false on failure.
+     *
+     * `opts.onCardSent` 回传卡片的 messageId：终态卡收尾后还要靠它接收后台任务
+     * 更新（流式卡从 `cardSession.cardMessageId` 取，兜底发送只能从这里拿）。
+     */
+    sendResult(result: CommandResult, ctx: CommandContext, opts?: {
+        onCardSent?: (messageId: string) => void;
+    }): Promise<boolean>;
     /**
      * Deliver a final answer that cannot fit in the run card as a Markdown file
      * attachment. 卡片正文已被标记替代，文件是唯一的内容通道；此处绝不发纯文本
-     * （2026-11-02 定规：纯文本与卡片重复，也丢 Markdown 结构）。
+     * （纯文本与卡片重复，也丢 Markdown 结构）。
      *
-     * 失败时发一张提示卡（不是纯文本），并把完整回答留在临时文件里记日志，
-     * 便于事后找回。
+     * 发送成功即清理临时文件；失败时发一张提示卡（不是纯文本），完整回答
+     * 留在临时文件里（路径见错误日志），便于事后找回。
      */
     private sendFinalAnswerFile;
     /**
@@ -413,14 +478,7 @@ export declare class Bridge {
      * 与 activeRuns 生命周期在同一个地方收口。
      */
     private rememberRunCardSnapshot;
-    /**
-     * 停止终态卡上的一个后台任务。
-     *
-     * 后台任务的生命周期跨 run（这就是它需要单独入口的原因），所以解析路径是
-     * 终态快照（runId → sessionId/cwd/agentKind）+ 该工作区的 runner 实例，
-     * 而不是 activeRuns。成功后同步摘掉 state 里的任务并就地重渲染，否则按钮
-     * 会留在卡片上而任务早已结束。
-     */
+    /** 停止终态卡上的一个后台任务（job.kill 卡片动作）。 */
     killBackgroundJob(runId: string, jobId: string, ctx: CommandContext): Promise<boolean>;
     /** Send a file to the user via Feishu. */
     sendFile(filePath: string, ctx: CommandContext): Promise<void>;
@@ -453,7 +511,7 @@ export declare class Bridge {
      *
      * DSH 把上游 `finish_reason: content_filter` 归一成 PI_AI_ERROR：既不在默认
      * 重试码里（EMPTY_RESPONSE/RATE_LIMIT/SERVER/TIMEOUT/TRANSPORT），也不会换模型，
-     * 于是一次（多数是误报的）判定就把整个 turn 判死。2026-10-21 现场：60 步、
+     * 于是一次（多数是误报的）判定就把整个 turn 判死。60 步、
      * 10 分钟的 turn 在最后一步被截断，已写入的文件还在，用户只看到「运行出错」
      * 加一句英文报文。
      *
@@ -483,7 +541,7 @@ export declare class Bridge {
      * result 在 system.init 之后才到。
      *
      * 例外：app-server runner（usageAuthority==='live'）的 init 是 runner 自己补发
-     * 的 synthetic init（2026-08-13 修复）。此分支保留为防御性兜底：live runner 若
+     * 的 synthetic init。此分支保留为防御性兜底：live runner 若
      * 在无 init 时发出 result（旧构建等），session 写回照常执行，但 sawResult 不置
      * 真——卡片不会把半初始化的 run 当作已收尾。
      *
@@ -511,6 +569,22 @@ export declare class Bridge {
      * Handles idle watchdog, event processing, session sync, and state transitions.
      */
     private runAgentStreamToEnd;
+    /**
+     * 事件循环的看门狗喂狗（runAgentStreamToEnd 抽出的纯向方法）。
+     *
+     * §9.12：事件到达只 `touch()` 刷新时间戳（无 timer 操作），interval 周期检查
+     * 静默时长；喂狗点与红线口径见 runAgentStreamToEnd 循环内两处调用点注释
+     * （每个事件含 result 都必须喂，被守卫丢弃的 result 也喂——CLI 活着就在产事件）。
+     */
+    private handleEventForWatchdog;
+    /**
+     * 事件循环的 session 同步（runAgentStreamToEnd 抽出的纯向方法）：
+     * init / turn_started 两写回点 + compact_boundary 用量观察。
+     *
+     * @returns 事件是否为本轮 `system.init`（调用方据此置 sawInit，供 pre-init
+     * result 守卫判定）。init 分支的全部副作用完成后才返回，与原内联顺序一致。
+     */
+    private maybeSyncSession;
     /**
      * 终态 reaction 收尾：撤掉 Typing、打上下方终态表情。
      *
@@ -584,89 +658,16 @@ export declare class Bridge {
         text: string;
         nonce: string;
     }): Promise<void>;
-    /**
-     * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
-     * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
-     * 超出上限按插入序淘汰最旧的一条（Map 保持插入序；重复写同一 runId
-     * 先 delete 再 set 以刷新位置）。
-     */
-    private recordCompactableRun;
-    /**
-     * 终态 Compact 记账：把本次 run 实际使用的 sessionId 记进
-     * {@link compactableRuns}，供终态卡上的 Compact 按钮按 runId 反查。
-     *
-     * 调用点固定在 `finalizeRun` 的 `finally` 里、**槽位所有权守卫之外**。
-     * 所有权守卫只回答「cwd 槽位还归不归本 run」（决定能否删槽位 / evict
-     * runner）；记账回答「本次 run 结束了吗、用的哪个 sessionId」。两者在不同
-     * 维度上：外部中断（`/stop`、停止卡按钮、`queue.immediate`）会先摘槽位，
-     * 记账若跟着守卫走就永远不会落，中断卡片的按钮必然反查不到（中断
-     * 后点 Compact 一律回「该任务已结束或不属于当前会话」）。
-     *
-     * 覆盖所有终态入口（正常结束、error、interrupted、idle_timeout、
-     * goal_continuing）——这些卡片都渲染 Compact 按钮（`goal` 仍 active 时
-     * 除外）。记账失败不能影响清理，故内部兜错。
-     */
-    private recordCompactableRunForTerminal;
-    /**
-     * 按 runId 反查可压缩 run 记录（跨 cwd 扫描）。
-     *
-     * 为什么不带 cwd 过滤：按钮属于「那一次 run」，与用户此刻在哪个工作目录、
-     * 排队期间有没有 /cd 无关。`/stop` 的 interruptCurrentRun 同样是全局按 runId
-     * 找（从不查当前 cwd），compact 与它保持一致。用当前 cwd 收窄会让「切了工作区
-     * 再点旧卡片」和「排队期间 /cd」两种情况误报「该任务已结束或不属于当前会话」。
-     */
-    private findCompactableRun;
-    /**
-     * Handle compact card action — trigger a compaction request for any
-     * runCompact-capable runner（codex/kimi/opencode/pi/claude）。按钮带的是
-     * 那次 run 的 runId，据此反查该 run 实际使用的 sessionId + agentKind
-     * + cwd（compactableRuns，按 runId 记录），再调 runner 的 runCompact()。
-     */
+    /** 终态卡 Compact 按钮：按 runId 反查那次 run 的会话并发起压缩。 */
     handleCompactAction(value: {
         runId?: string;
     }, ctx: CommandContext): Promise<void>;
-    /**
-     * §5.3: kimi 压缩在途检测——reader 实现契约的 `readCompactionState` 时，若
-     * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
-     * 直接回文本「已有一次 Compact 正在进行」并返回 true（调用方不开卡、不发
-     * session/prompt）。codex/claude 等 reader 无此方法 → 返回 false，行为不变。
-     */
-    private rejectIfCompactionInFlight;
-    /**
-     * Stream a compaction to a card: start a RunCardSession with
-     * operationKind='compaction' (no recursive Compact button), consume
-     * runner.runCompact() events, read authoritative jsonl usage, and finish
-     * the card. Shared by handleCompactAction (run card button) and
-     * handleResumeCompact (resume cards) so both flows stay in sync.
-     *
-     * Precondition: callers have already validated that `runner` implements
-     * runCompact and that the session exists in `cwd`.
-     */
-    private streamCompact;
-    /**
-     * Handle resume.compact card action — compact a session directly from a
-     * resume card (auto-resume / `/resume <id>`), without a runId.
-     *
-     * Unlike handleCompactAction (which validates against the last finished run's
-     * runId), the resume card carries the sessionId + agent it was rendered for.
-     * Validation: the session must exist in the current cwd (same rule as
-     * cmdResume / resume.use) and the runner must implement runCompact.
-     */
+    /** resume 卡 Compact 按钮：直接压缩卡上指定的 session（无需 runId）。 */
     handleResumeCompact(value: {
         sessionId?: string;
         agent?: string;
     }, ctx: CommandContext): Promise<void>;
-    /**
-     * Execute a bash command and stream output to a card.
-     * `!` commands bypass the serial queue entirely (see body comment + §9.6):
-     * bash runs in parallel with same-workspace agent runs, tracked in
-     * `activeBashRuns` separately from `activeRuns`.
-     */
+    /** Execute a bash command and stream output to a card（`!` 命令入口）。 */
     executeBash(command: string, ctx: CommandContext): Promise<void>;
-    /**
-     * Internal execution of bash command (called directly from executeBash,
-     * bypassing the serial queue — see executeBash).
-     */
-    private executeBashInternal;
 }
 export {};