lark-remote 0.5.19 → 0.5.21

package/dist/bridge/job-watch.d.ts

@@ -0,0 +1,68 @@
+import type { Runner } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { CommandContext } from './index.js';
+import type { RunCardSnapshot } from './index.js';
+/**
+ * 终态卡后台任务订阅与停止（bridge 结构治理第 2 刀）。
+ *
+ * run 的卡片在 `result` 那一帧就关闭了，但后台任务（DSH/kimi 的宿主后台作业）
+ * 的生命周期跨 run：job.kill 停止、名单订阅、PATCH 串行链全部收在这里，与
+ * 卡片快照（bridge 侧 runCardSnapshots）按 runId 对齐。
+ *
+ * 依赖显式注入（与 ApprovalActions / CompactLifecycle 同一模式）。两张核心
+ * 状态表都归本类所有：
+ * - `jobWatches`：runId → 中止句柄。与卡片快照同生命周期——快照被淘汰、任务
+ *   全结束、patch 失败时退订。上限天然受 RUN_CARD_SNAPSHOT_MAX 约束（一张卡
+ *   最多一条流）。
+ * - `jobCardPatches`：同一张卡的 patch 串行链（runId → 链尾）。「停止按钮」和
+ *   「订阅帧」都会改同一张终态卡：不串行化时两条 PATCH 并发，后发先至的那条
+ *   会把卡片写回旧内容（任务又变回「运行中」）。
+ */
+export interface JobWatchLifecycleDeps {
+    getRunner(cwd: string, kind?: AgentKind): Runner;
+    /** 终态快照表在 bridge 侧（rememberRunCardSnapshot 收口），这里只读。 */
+    getRunCardSnapshot(runId: string): RunCardSnapshot | undefined;
+    /** 「停止任务」后的整卡重渲染（失败回退发新卡）。 */
+    updateCardInPlace(card: object, ctx: CommandContext): Promise<boolean>;
+    /** 订阅帧的原位 PATCH（已知卡，失败不补发）。 */
+    patchCard(messageId: string, card: object): Promise<boolean>;
+}
+export declare class JobWatchLifecycle {
+    private readonly deps;
+    /** 终态卡后台任务订阅（runId → 中止句柄）。 */
+    private jobWatches;
+    /** 同一张卡的 patch 串行链（runId → 链尾）。 */
+    private jobCardPatches;
+    constructor(deps: JobWatchLifecycleDeps);
+    /** 退订一张终态卡的后台任务名单（幂等）。 */
+    stopJobWatch(runId: string): void;
+    /**
+     * 停止终态卡上的一个后台任务。
+     *
+     * 后台任务的生命周期跨 run（这就是它需要单独入口的原因），所以解析路径是
+     * 终态快照（runId → sessionId/cwd/agentKind）+ 该工作区的 runner 实例，
+     * 而不是 activeRuns。成功后同步摘掉 state 里的任务并就地重渲染，否则按钮
+     * 会留在卡片上而任务早已结束。
+     */
+    killBackgroundJob(runId: string, jobId: string, ctx: CommandContext): Promise<boolean>;
+    /**
+     * 让终态卡的后台任务小节跟着宿主继续更新。
+     *
+     * run 的卡片在 `result` 那一帧就关闭了，但后台任务还能再跑很久：不订阅，
+     * 卡片会一直写「运行中」并留着停止按钮，点了必然失败。退订条件写
+     * 在 {@link consumeJobRoster} 里——名单清空、patch 失败、订阅中断、快照被
+     * 淘汰，任一命中即退出；**绝不因为 patch 失败补发新卡**。
+     */
+    startBackgroundJobWatch(runId: string, snapshot: RunCardSnapshot, runner: Runner): void;
+    /** 消费宿主推来的整份任务名单，直到全结束 / 流断 / patch 失败 / 外部退订。 */
+    private consumeJobRoster;
+    /** 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」并重渲染一次。 */
+    private markJobsUnknown;
+    /**
+     * 一张终态卡的 PATCH 串行链。
+     *
+     * 渲染放在链内执行（`task` 里读 `snapshot.state`），后入链的任务必然看到更新
+     * 后的状态；否则「停止」与「订阅帧」并发时卡片可能回退。
+     */
+    private enqueueJobCardPatch;
+}

package/dist/bridge/job-watch.js

@@ -0,0 +1,146 @@
+import { isLiveBackgroundJob, markBackgroundJobsUnknown, removeBackgroundJob, syncBackgroundJobs, } from '../card/run-state.js';
+import { renderRunCard } from '../card/run-renderer.js';
+import { getLogger } from '../logger/index.js';
+import { errorMessage } from './final-usage.js';
+export class JobWatchLifecycle {
+    deps;
+    /** 终态卡后台任务订阅（runId → 中止句柄）。 */
+    jobWatches = new Map();
+    /** 同一张卡的 patch 串行链（runId → 链尾）。 */
+    jobCardPatches = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 退订一张终态卡的后台任务名单（幂等）。 */
+    stopJobWatch(runId) {
+        this.jobWatches.get(runId)?.abort();
+        this.jobWatches.delete(runId);
+        this.jobCardPatches.delete(runId);
+    }
+    /**
+     * 停止终态卡上的一个后台任务。
+     *
+     * 后台任务的生命周期跨 run（这就是它需要单独入口的原因），所以解析路径是
+     * 终态快照（runId → sessionId/cwd/agentKind）+ 该工作区的 runner 实例，
+     * 而不是 activeRuns。成功后同步摘掉 state 里的任务并就地重渲染，否则按钮
+     * 会留在卡片上而任务早已结束。
+     */
+    async killBackgroundJob(runId, jobId, ctx) {
+        const snapshot = this.deps.getRunCardSnapshot(runId);
+        const sessionId = snapshot?.state.sessionId;
+        if (!snapshot || !sessionId)
+            return false;
+        const runner = this.deps.getRunner(snapshot.cwd, snapshot.agentKind);
+        if (typeof runner.killJob !== 'function')
+            return false;
+        const killed = await runner.killJob(sessionId, jobId);
+        if (!killed)
+            return false;
+        snapshot.state = removeBackgroundJob(snapshot.state, jobId);
+        // 与订阅帧共用一条串行链：两条 PATCH 并发时，后发先至的那条会把卡片写回
+        // 旧内容（刚停掉的任务又显示成「运行中」）。
+        await this.enqueueJobCardPatch(runId, async () => {
+            await this.deps.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
+            return true;
+        });
+        // 卡片上已经没有在跑的任务：不必再等宿主推下一帧，直接退订。
+        if (!(snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob)) {
+            this.stopJobWatch(runId);
+        }
+        return true;
+    }
+    /**
+     * 让终态卡的后台任务小节跟着宿主继续更新。
+     *
+     * run 的卡片在 `result` 那一帧就关闭了，但后台任务还能再跑很久：不订阅，
+     * 卡片会一直写「运行中」并留着停止按钮，点了必然失败。退订条件写
+     * 在 {@link consumeJobRoster} 里——名单清空、patch 失败、订阅中断、快照被
+     * 淘汰，任一命中即退出；**绝不因为 patch 失败补发新卡**。
+     */
+    startBackgroundJobWatch(runId, snapshot, runner) {
+        const live = (snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob);
+        if (!live)
+            return;
+        const sessionId = snapshot.state.sessionId;
+        const messageId = snapshot.messageId;
+        const watchJobs = runner.watchJobs;
+        if (!sessionId || !messageId || typeof watchJobs !== 'function') {
+            // 没有卡 id 就没有 patch 的落点：保留收尾快照，不另发一张卡。
+            getLogger().info(`[lark-remote] background jobs stay on the turn snapshot runId=${runId} ` +
+                `(sessionId=${sessionId ?? '-'} messageId=${messageId ?? '-'} watchable=${typeof watchJobs === 'function'})`);
+            return;
+        }
+        const controller = new AbortController();
+        this.jobWatches.set(runId, controller);
+        void this.consumeJobRoster(runId, snapshot, controller, (signal) => watchJobs.call(runner, sessionId, signal));
+    }
+    /** 消费宿主推来的整份任务名单，直到全结束 / 流断 / patch 失败 / 外部退订。 */
+    async consumeJobRoster(runId, snapshot, controller, watch) {
+        const messageId = snapshot.messageId;
+        if (!messageId)
+            return;
+        let allEnded = false;
+        // 订阅帧 PATCH 已失败 → 卡片不可达：finally 不再补 markJobsUnknown。
+        let cardLost = false;
+        try {
+            for await (const roster of watch(controller.signal)) {
+                const next = syncBackgroundJobs(snapshot.state, roster);
+                // 名单没变化就不打 PATCH：宿主可能重复推同一份。
+                if (next === snapshot.state)
+                    continue;
+                snapshot.state = next;
+                const ok = await this.enqueueJobCardPatch(runId, () => this.deps.patchCard(messageId, renderRunCard(snapshot.state, snapshot.options)));
+                if (!ok) {
+                    getLogger().warn(`[lark-remote] background job card update failed, stop watching runId=${runId}`);
+                    // 卡片已不可达：markJobsUnknown 的补写注定再失败，且「标未知」
+                    // 是写给卡片读者看的——没有卡就没有读者。置标志让 finally 跳过。
+                    cardLost = true;
+                    return;
+                }
+                if (!(snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob)) {
+                    allEnded = true;
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            if (!controller.signal.aborted) {
+                getLogger().warn(`[lark-remote] background job watch failed runId=${runId}: ${errorMessage(err)}`);
+            }
+        }
+        finally {
+            const externallyAborted = controller.signal.aborted;
+            controller.abort();
+            // 流断了而任务没结算：监控中断 ≠ 任务结束，标成未知而不是继续写「运行中」。
+            // 但卡片 PATCH 已失败（cardLost）时不补写：补写注定失败且语义错位。
+            if (!allEnded && !cardLost && !externallyAborted)
+                await this.markJobsUnknown(runId, snapshot);
+            this.jobWatches.delete(runId);
+            this.jobCardPatches.delete(runId);
+        }
+    }
+    /** 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」并重渲染一次。 */
+    async markJobsUnknown(runId, snapshot) {
+        const next = markBackgroundJobsUnknown(snapshot.state);
+        if (next === snapshot.state)
+            return;
+        snapshot.state = next;
+        const messageId = snapshot.messageId;
+        if (!messageId)
+            return;
+        await this.enqueueJobCardPatch(runId, () => this.deps.patchCard(messageId, renderRunCard(snapshot.state, snapshot.options)));
+    }
+    /**
+     * 一张终态卡的 PATCH 串行链。
+     *
+     * 渲染放在链内执行（`task` 里读 `snapshot.state`），后入链的任务必然看到更新
+     * 后的状态；否则「停止」与「订阅帧」并发时卡片可能回退。
+     */
+    enqueueJobCardPatch(runId, task) {
+        const previous = this.jobCardPatches.get(runId) ?? Promise.resolve();
+        const next = previous.then(task, task);
+        this.jobCardPatches.set(runId, next.then(() => undefined, () => undefined));
+        return next;
+    }
+}
+//# sourceMappingURL=job-watch.js.map

package/dist/bridge/queue-manager.d.ts

@@ -11,7 +11,7 @@ export interface AgentBinding {
      * 会话代际快照（与 sessionId 同刻捕获）。随 binding 带到执行时刻：若执行前
      * session 指针被移动（/new、/cd、/resume、/config 切换），该 run 的 init /
      * turn_started 写回判 stale 跳过，避免「先发消息 → 后点新会话」时旧 sessionId
-     * 被写回复活（2026-10-07 事故）。缺省时回退到执行起点捕获，保持旧行为。
+     * 被写回复活。缺省时回退到执行起点捕获，保持旧行为。
      */
     sessionEpoch?: number;
 }
@@ -161,7 +161,7 @@ export declare class QueueManager {
      * interrupt credit to exactly the interrupted task's slot) and the display
      * info the queue card needs to name what a waiting message waits for.
      *
-     * 2026-10-09 线上：一次 Compact 占着 lane，新消息的排队卡却写「位置: 第 1
+     * 一次 Compact 占着 lane，新消息的排队卡曾写「位置: 第 1
      * 位 / 前面还有: 0 条消息」——开卡判据看 lane（含正在执行者），位置文案只看
      * 等待队列，两个口径的差集正是这条记录。
      */
@@ -276,7 +276,7 @@ export declare class QueueManager {
     /**
      * 排队卡头部。只有前面确实还有等待中的消息时才说「排队」；前面为空时
      * 用户等的是当前正在执行的任务（例如 Compact），用「等待当前任务结束」
-     * 表达才不会与「前面还有 0 条」自相矛盾（2026-10-09 线上实例）。
+     * 表达才不会与「前面还有 0 条」自相矛盾。
      */
     private queueCardHeader;
     /** Send a queue status card showing current queue position and actions. */

package/dist/bridge/queue-manager.js

@@ -1,5 +1,5 @@
 import { getLogger } from '../logger/index.js';
-import { cardWithHeader } from '../card/card-shared.js';
+import { cardButton, cardWithHeader } from '../card/card-shared.js';
 import { displayName } from '../platform/path.js';
 /**
  * Per-workspace cap on the number of tasks WAITING to execute.
@@ -71,7 +71,7 @@ export class QueueManager {
      * interrupt credit to exactly the interrupted task's slot) and the display
      * info the queue card needs to name what a waiting message waits for.
      *
-     * 2026-10-09 线上：一次 Compact 占着 lane，新消息的排队卡却写「位置: 第 1
+     * 一次 Compact 占着 lane，新消息的排队卡曾写「位置: 第 1
      * 位 / 前面还有: 0 条消息」——开卡判据看 lane（含正在执行者），位置文案只看
      * 等待队列，两个口径的差集正是这条记录。
      */
@@ -227,8 +227,8 @@ export class QueueManager {
         }
         // 身份不变量 tripwire：同一 cwd 内 queue key 必须唯一（一次入队动作一个
         // key，铸造点 router.mintQueueTaskKey）。撞 key 时数组（追加）与 taskIndex
-        // （覆盖）必然漂移，位置显示/撤销/立即执行/卡片更新会串到别的条目上——
-        // 2026-10-08 线上缺陷就是这么长出来的。这里不改行为，只留证据。
+        // （覆盖）必然漂移，位置显示/撤销/立即执行/卡片更新会串到别的条目上。
+        // 这里不改行为，只留证据。
         if (this.indexGet(cwd, queuedTask.messageId)) {
             getLogger().warn(`[queue-manager] duplicate queue key cwd=${cwd} messageId=${queuedTask.messageId} — ` +
                 'queue identity must be minted per enqueue action (see router.mintQueueTaskKey)');
@@ -304,8 +304,7 @@ export class QueueManager {
             // so pruning the oldest entries is safe.
             if (this.beganMessageIds.size >= 10_000) {
                 const oldest = this.beganMessageIds.values().next().value;
-                if (oldest !== undefined)
-                    this.beganMessageIds.delete(oldest);
+                this.beganMessageIds.delete(oldest);
             }
             this.beganMessageIds.add(messageId);
         }
@@ -453,7 +452,7 @@ export class QueueManager {
     /**
      * 排队卡头部。只有前面确实还有等待中的消息时才说「排队」；前面为空时
      * 用户等的是当前正在执行的任务（例如 Compact），用「等待当前任务结束」
-     * 表达才不会与「前面还有 0 条」自相矛盾（2026-10-09 线上实例）。
+     * 表达才不会与「前面还有 0 条」自相矛盾。
      */
     queueCardHeader(tasksAhead) {
         return {
@@ -537,7 +536,7 @@ export class QueueManager {
         if (occupant) {
             // 只有可能挡住队列、需要用户归因的占用者才自报身份。「正在执行: 💬 消息」
             // 对普通消息占用者没有信息量——用户刚发的就是消息，「💡 消息将按顺序执行…」
-            // 也只是复述排队本身，一并省去（2026-10-11）。压缩额外说明何时轮到用户。
+            // 也只是复述排队本身，一并省去。压缩额外说明何时轮到用户。
             if (occupant.kind !== 'message') {
                 elements.push({
                     tag: 'div',
@@ -572,13 +571,7 @@ export class QueueManager {
                 // Edit button: a pending (queued) task is editable by default. The
                 // executing/cancelled states render via dedicated card builders that
                 // hard-disable all buttons, so this builder only serves pending cards.
-                elements.push({
-                    tag: 'button',
-                    text: { tag: 'plain_text', content: '✏️ 编辑' },
-                    type: 'default',
-                    size: 'small',
-                    behaviors: [{ type: 'callback', value: { cmd: 'queue.edit', cwd, messageId } }],
-                });
+                elements.push(cardButton('✏️ 编辑', { cmd: 'queue.edit', cwd, messageId }, { type: 'default', size: 'small' }));
             }
             elements.push({ tag: 'hr' });
         }
@@ -604,20 +597,8 @@ export class QueueManager {
      */
     buildQueueActionButtons(cwd, messageId, disabled, opts) {
         return [
-            {
-                tag: 'button',
-                text: { tag: 'plain_text', content: '❌ 撤销' },
-                type: 'danger',
-                disabled,
-                behaviors: [{ type: 'callback', value: { cmd: 'queue.cancel', cwd, messageId } }],
-            },
-            {
-                tag: 'button',
-                text: { tag: 'plain_text', content: opts?.immediateLabel ?? '⚡ 立即执行' },
-                type: 'primary',
-                disabled: disabled || opts?.immediateLabel !== undefined,
-                behaviors: [{ type: 'callback', value: { cmd: 'queue.immediate', cwd, messageId } }],
-            },
+            cardButton('❌ 撤销', { cmd: 'queue.cancel', cwd, messageId }, { type: 'danger', disabled }),
+            cardButton(opts?.immediateLabel ?? '⚡ 立即执行', { cmd: 'queue.immediate', cwd, messageId }, { type: 'primary', disabled: disabled || opts?.immediateLabel !== undefined }),
         ];
     }
     /**

package/dist/card/approval-render.d.ts

@@ -10,7 +10,7 @@ import { type RunTerminal } from './run-state.js';
  * Render the approval area for a run card.
  * Returns an array of CardKit 2.0 elements to append to the card body.
  */
-export declare function renderApprovalArea(approval: ApprovalView | undefined, opts?: {
+export declare function renderApprovalArea(approval: ApprovalView, opts?: {
     expired?: boolean;
     runId?: string;
     terminal?: RunTerminal;
@@ -24,7 +24,7 @@ export declare function renderApprovalArea(approval: ApprovalView | undefined, o
  * 层一起超限，超限卡被飞书整卡拒收（11310）→ 审批不可见。兜底层换用本入口后
  * 结构性保证 ≤ 几个元素 + ≤ 1KB 文本，审批入口（红线）在任何降级档都活着。
  */
-export declare function renderApprovalAreaCompact(approval: ApprovalView | undefined, opts?: {
+export declare function renderApprovalAreaCompact(approval: ApprovalView, opts?: {
     expired?: boolean;
     runId?: string;
     terminal?: RunTerminal;