lark-remote 0.1.0

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

@@ -0,0 +1,277 @@
+import type { AgentKind } from '../runner/types.js';
+/**
+ * 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
+ * 唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
+ * 执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。
+ */
+export interface AgentBinding {
+    agent: AgentKind;
+    sessionId?: string;
+}
+/** A queued task with its metadata for queue display cards. */
+export interface QueuedTask {
+    userId: string;
+    chatId: string;
+    /**
+     * Queue dedup/identity key. For hand-typed messages this is the Feishu
+     * message id; for card-action dispatches (e.g. `order.exec`, where one card
+     * is clickable N times) this is a project-minted internal key (NOT a valid
+     * Feishu message id). It is used for task lookup, cancellation, and queue
+     * card button callbacks — never as a Feishu reply target.
+     */
+    messageId: string;
+    /**
+     * The Feishu message id the queue status card should reply to, when it
+     * differs from `messageId` (i.e. `messageId` is an internal key). Falls back
+     * to `messageId` for hand-typed messages, where the two coincide.
+     */
+    feishuReplyTo?: string;
+    workspace: string;
+    timestamp: number;
+    messagePreview: string;
+    /**
+     * Edited message content. Set by `updateQueuedTaskMessage` when the user
+     * edits a queued message. The original closure captured at enqueue time
+     * is immutable, so `handleQueueImmediate` reads this field to register a
+     * one-shot replacement closure with the edited content (see router
+     * `handleQueueImmediate`).
+     */
+    editedMessage?: string;
+    /** 入队时刻捕获的 agent+session 绑定（方案 D4），随任务闭包带到执行时刻。 */
+    binding?: AgentBinding;
+}
+/** Options for enqueue operation */
+export interface EnqueueOptions {
+    taskMeta?: {
+        userId: string;
+        chatId: string;
+        messageId: string;
+        messagePreview: string;
+        /**
+         * Feishu message id the queue status card should reply to, when the queue
+         * dedup key (`messageId`) is NOT a valid Feishu id (e.g. an order.exec
+         * internal key). Omitted for hand-typed messages, where `messageId` is the
+         * real Feishu id and doubles as the reply target.
+         */
+        feishuReplyTo?: string;
+        /** 入队时刻捕获的 agent+session 绑定（方案 D4）。 */
+        binding?: AgentBinding;
+    };
+}
+/** Queue info for a workspace */
+interface QueueInfo {
+    position: number;
+    tasksAhead: number;
+    isRunning: boolean;
+}
+/**
+ * QueueManager handles the per-workspace serial processing queue.
+ * Manages task queuing, cancellation, and queue status card rendering.
+ */
+export declare class QueueManager {
+    /** Per-workspace (cwd) serial queues. Key = cwd, value = tail of promise chain. */
+    private queues;
+    /** Per-workspace queued tasks for queue display cards. Key = cwd, value = task list. */
+    private queuedTasks;
+    /**
+     * P3-5: per-workspace `messageId → QueuedTask` index mirroring `queuedTasks`.
+     * O(1) lookup for the task-start removal path (replacing the old double
+     * `find`+`findIndex` O(N) scan) and for `getQueuedTask`/`removeFromQueue`/
+     * `updateQueuedTaskMessage`. The ordered array remains the source of truth
+     * (position display depends on order); the index must be kept in sync on
+     * every mutation (push / splice / shift) via the `indexAdd`/`indexRemove`
+     * helpers. Same messageId is never enqueued twice in one workspace
+     * (Feishu dedup + internal-key dedup), so no overwrite concern.
+     */
+    private taskIndex;
+    /**
+     * Map from user messageId to the queue card's Feishu send promise. Storing
+     * the promise (not the resolved id) closes the race where the card send is
+     * still in flight when the task begins: the begin path awaits the stored
+     * promise, so a late-arriving card id still gets reconciled to the
+     * executing/cancelled state. The promise never rejects (send failures
+     * resolve undefined), so awaiting it is always safe.
+     */
+    private queueCardMessages;
+    /** Track number of executing tasks per workspace (for queue card display). */
+    private pendingOrExecutingCount;
+    /**
+     * Monotonic counter minting a unique slot id per enqueued task. A slot
+     * identifies one task's execution period for the interrupt bookkeeping in
+     * `executingSlot`/`interruptedSlots` — replacing the unowned skip-credit
+     * counter, which any settle could consume and which therefore leaked a
+     * re-armed count after repeated resets (see A4 anchor).
+     */
+    private slotCounter;
+    /**
+     * Per-workspace slot id of the task currently executing. Set in the begin
+     * path right before the task runs; deleted when that task's settle fires.
+     * `resetExecutingCount` reads it to bind the interrupt credit to exactly
+     * the interrupted task's slot.
+     */
+    private executingSlot;
+    /**
+     * Per-workspace set of slot ids whose task was interrupted by
+     * `resetExecutingCount`. When such a slot settles, its decrement is skipped
+     * (the reset already zeroed the count). A slot is granted at most once —
+     * repeated resets of the same executing task do not mint extra credits —
+     * which prevents a normal task's settle from consuming a credit instead of
+     * decrementing, leaking the re-armed count to 1.
+     */
+    private interruptedSlots;
+    /** Per-workspace messageId → replacement closure, set by queue.edit + immediate. */
+    private taskReplacements;
+    /**
+     * MessageIds of tasks that have actually begun executing (cancellation check
+     * passed, task removed from the queue). Entries are sticky: they remain
+     * after the task settles (A21). `handleQueueImmediate` step 6 uses this to
+     * distinguish "target was cancelled (never began)" from "target began while
+     * the interrupt was in flight" so the final feedback can report the true
+     * state instead of telling a running task's user that nothing was
+     * scheduled. A task that began and then settled quickly must still report
+     * "已开始执行", which requires the marker to survive settle. Message ids are
+     * globally unique and never reused, so a sticky marker cannot misclassify a
+     * later task; the set is bounded-pruned on insert to prevent unbounded
+     * growth. Removed/cancelled tasks never enter the set (cancellation happens
+     * before begin); `removeFromQueue` therefore needs no cleanup here.
+     */
+    private beganMessageIds;
+    /** Callback to check if workspace has an active run */
+    private isWorkspaceRunning;
+    /** Callback to send card updates */
+    private sendCard;
+    /** Callback to update existing card */
+    private updateCard;
+    constructor(isWorkspaceRunning: (workspace: string) => boolean, sendCard: (chatId: string, card: object, opts?: {
+        replyTo?: string;
+    }) => Promise<string>, updateCard: (messageId: string, card: object) => Promise<void>);
+    /** P3-5: register a queued task in the per-workspace `messageId → task` index. */
+    private indexAdd;
+    /** P3-5: drop a task from the per-workspace index by messageId. */
+    private indexRemove;
+    /** P3-5: O(1) lookup of a queued task by messageId via the index. */
+    private indexGet;
+    /**
+     * Enqueue a task into the workspace-level serial queue.
+     * Each workspace has its own serial queue for parallel execution across workspaces.
+     */
+    enqueue(workspace: string, task: () => Promise<void>, opts?: EnqueueOptions): void;
+    /**
+     * Execute a task immediately without going through the queue.
+     * Used for / commands that should respond immediately.
+     */
+    enqueueImmediate(workspace: string, task: () => Promise<void>): void;
+    /**
+     * One-shot: replace the execution closure of an existing queued task in
+     * place, preserving its queue position (tasks queued behind it still run
+     * after it). Consumed when the task's slot begins; removed if cancelled.
+     */
+    setTaskReplacement(workspace: string, messageId: string, task: () => Promise<void>): void;
+    /** Send a queue status card showing current queue position and actions. */
+    private sendQueueStatusCard;
+    /** Get queue info for a workspace. */
+    getQueueInfo(workspace: string): QueueInfo;
+    /** Build queue status card elements. */
+    private buildQueueStatusCardElements;
+    /**
+     * Build the 撤销/立即执行 action button pair for a queue card.
+     *
+     * Both buttons route to `queue.cancel` / `queue.immediate` callbacks with
+     * the same workspace/messageId; only the `disabled` flag varies by card
+     * state — pending cards enable both, executing/cancelled cards disable
+     * both. Centralizing the pair here eliminates the 3-way duplication
+     * between `buildQueueStatusCardElements`, `updateQueueCardToExecuting`,
+     * and `updateQueueCardToCancelled` (Clean Code P2-1).
+     */
+    private buildQueueActionButtons;
+    /**
+     * Update queue card to "started executing" status when task begins.
+     *
+     * `started` tells the method whether the caller has already confirmed the
+     * task really began (begin path: cancellation check passed and the task has
+     * been removed from the queue). When `started` is false (queue.immediate
+     * mark path), a membership guard re-checks the task right before the card
+     * update: if the task was removed/cancelled while the send was in flight,
+     * the card must keep its "❌ 已撤销" state instead of being flipped back to
+     * executing. The mapping is deleted in finally in both cases.
+     */
+    updateQueueCardToExecuting(workspace: string, messageId: string, messagePreview: string, started?: boolean): Promise<void>;
+    /** Remove a task from the queue by messageId. Returns true if found and removed. */
+    removeFromQueue(workspace: string, messageId: string): boolean;
+    /** Update queue card to "cancelled" status when user clicks 撤销. */
+    updateQueueCardToCancelled(workspace: string, messageId: string): Promise<void>;
+    /** Get task metadata from queue. */
+    getQueuedTask(workspace: string, messageId: string): QueuedTask | undefined;
+    /**
+     * Whether a task with the given messageId has begun executing (cancellation
+     * check passed, task removed from the queue). Sticky: true even after the
+     * task settles, so queue.immediate can distinguish "began (possibly already
+     * completed)" from "never began / cancelled".
+     */
+    hasBegan(messageId: string): boolean;
+    /** Get all queued tasks for a workspace. Returns a copy to prevent aliasing bugs. */
+    getQueuedTasks(workspace: string): QueuedTask[];
+    /** Update the messagePreview for a queued task. Returns true if found and updated. */
+    updateQueuedTaskMessage(workspace: string, messageId: string, newMessage: string): boolean;
+    /**
+     * Build the orange queue card reflecting the edited message content. Returns
+     * the card object (sent as the cardAction callback response `card.data`,
+     * which Feishu renders in place) or null if the task is no longer queued.
+     *
+     * Why a callback-response card instead of a PATCH updateCard API call:
+     * when handleQueueInput returns a { toast } callback response, Feishu uses
+     * that response to render the clicked card; a response without a `card`
+     * field leaves the card in its pre-click (edit) state, overriding the
+     * concurrent PATCH updateCard result. Returning { card } in the callback
+     * response updates the card synchronously with no API race.
+     */
+    buildQueueCardForEdit(workspace: string, messageId: string, newMessagePreview: string): object | null;
+    /**
+     * Decrement `pendingOrExecutingCount` for a workspace, honoring per-slot
+     * interrupt bookkeeping.
+     *
+     * Called from the queue chain's `.then()`/`.catch()` settle with the slot
+     * id minted at enqueue time. Three cases:
+     *
+     * 1. The slot is the workspace's current executing slot → its execution
+     *    period ends (`executingSlot` marker removed).
+     * 2. The slot is in `interruptedSlots` (its task was interrupted by
+     *    `resetExecutingCount`) → skip the decrement: the reset already zeroed
+     *    the count, so a stale decrement could wrongly zero it again while a
+     *    newer task (enqueued after the reset) is still running.
+     * 3. Otherwise → normal decrement.
+     */
+    private decrementExecutingCount;
+    /**
+     * Reset the executing task count for a workspace.
+     *
+     * This should be called when a running task is interrupted externally
+     * (e.g., via /stop command or "立即执行" button) so that the queue
+     * correctly reflects that no tasks are currently executing.
+     *
+     * Without this reset, the pendingOrExecutingCount would remain > 0 even after
+     * the task process is killed, causing subsequent messages to incorrectly
+     * show as "排队中" because the queue thinks a task is still running.
+     *
+     * Also marks the currently executing task's slot as interrupted, so its
+     * eventual `.then()`/`.catch()` settle skips the decrement (which could
+     * otherwise zero the count while a newer task is still running). The mark
+     * is granted at most once per slot: repeated resets of the same executing
+     * task do not accumulate credits.
+     *
+     * `expectedSlot` binds the reset to the task that was actually interrupted:
+     * the caller captures the executing slot BEFORE stopping the runner, and
+     * the stop window may outlive the interrupted task's settle (the chain can
+     * advance to a NEW task, which then owns `executingSlot`). When the current
+     * slot no longer matches the interrupted task's slot, the interrupted task
+     * already decremented normally — resetting now would zero the count of the
+     * running successor and mark ITS slot interrupted, hiding it from the
+     * queue card (A22).
+     */
+    resetExecutingCount(workspace: string, expectedSlot: number): void;
+    /**
+     * The slot id of the task currently executing in this workspace (if any).
+     */
+    getExecutingSlot(workspace: string): number | undefined;
+}
+export {};