lark-remote 0.1.0

package/dist/bridge/index.d.ts

@@ -0,0 +1,338 @@
+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 { type QueuedTask, type EnqueueOptions, type AgentBinding } from './queue-manager.js';
+/**
+ * Seam (§7): the channel capabilities the bridge needs. `sendWithRetry` is
+ * the minimum a Feishu channel must offer for the bridge to push messages
+ * through it; `reconnect` lets `/reconnect` be served through the bridge
+ * without the router holding a separate connector reference. Declared here
+ * so tests can satisfy it structurally without `as unknown as` casts.
+ */
+interface BridgeChannel extends RunCardChannel {
+    sendWithRetry(chatId: string, input: {
+        text: string;
+    } | {
+        markdown: string;
+    } | {
+        card: object;
+    }, opts?: {
+        replyTo?: string;
+    }): Promise<string>;
+    reconnect(): Promise<void>;
+    sendFile(chatId: string, filePath: string): Promise<string>;
+    addReaction(messageId: string, emoji: string): Promise<void>;
+}
+/** Caller context for a bridge operation. */
+interface BridgeContext {
+    userId: string;
+    chatId: string;
+    messageId: string;
+}
+/** A sendable result payload (mirror of the router's CommandResult shape). */
+interface BridgeResult {
+    text?: string;
+    markdown?: string;
+    card?: object;
+}
+export interface ActiveRunSnapshot {
+    runId: string;
+    userId: string;
+    chatId: string;
+    cwd: string;
+    sessionId?: string;
+    terminal: RunTerminal;
+    contextLength?: number;
+    compactCount?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+interface BridgeDeps {
+    runner: Runner;
+    connector: BridgeChannel;
+    sessionStore: SessionStore;
+    config: AppConfig;
+    /** Workspace store for fallback when sessionStore has no cwd */
+    workspaceStore?: {
+        get(name: string): string | undefined;
+        list(): [string, string][];
+    };
+    /** Override the idle watchdog timeout (default 15 min). Tests use a small value. */
+    idleTimeoutMs?: number;
+    /**
+     * Multi-agent registry. `getRunner(workspace)` looks up
+     * `config.defaultAgent` here.
+     */
+    agentRegistry: AgentRegistry;
+    /**
+     * Session reader registry. Used by `resolveFinalUsage` and
+     * `sendCompletionNotificationCard` to read session content via
+     * `registry.get(config.defaultAgent)`.
+     */
+    sessionReaderRegistry: SessionReaderRegistry;
+}
+/**
+ * Bridge owns the per-workspace serial processing queue (§9.6) and the
+ * single-card streaming forwarding loop (§9.12 watchdog + session sync).
+ *
+ * The router delegates non-command messages here via `forwardToClaude` and
+ * sends command results via `sendResult`. Serial processing is enforced per
+ * workspace by `enqueue`: each workspace has its own Promise chain, so at
+ * most one agent process runs per workspace at a time, while different
+ * workspaces run in parallel (see `activeRuns`, §9.6). This is a load-bearing
+ * invariant — concurrent spawns within one workspace would corrupt session
+ * state. Most card actions go through `enqueueImmediate` (fire-and-forget,
+ * outside the serial chain); only run-forwarding is serialized.
+ *
+ * The idle watchdog (§9.12) is also load-bearing: without it a hung agent
+ * process would block its workspace's serial queue forever. Both invariants
+ * now have a single owner (this class) and a test surface via the
+ * Runner/BridgeChannel seams.
+ */
+export declare class Bridge {
+    private runner;
+    private connector;
+    private sessionStore;
+    private config;
+    private workspaceStore?;
+    private idleTimeoutMs;
+    /** Multi-agent registry. */
+    private agentRegistry;
+    /** Session reader registry for usage and completion cards. */
+    private sessionReaderRegistry;
+    /**
+     * Per-workspace runner instances, keyed by (cwd, agentKind).
+     * Fix 4 (2026-07-18): 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
+     * blocked the queue forever.
+     */
+    private runners;
+    /** Queue manager for per-workspace serial processing queue. */
+    private queueManager;
+    /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
+    private activeRuns;
+    /**
+     * 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
+     * workspace, so they live outside `activeRuns`. Tracked so `/stop` can reach
+     * the per-run BashRunner instance via interruptCurrentRun.
+     */
+    private activeBashRuns;
+    constructor(deps: BridgeDeps);
+    /**
+     * Get or create a runner for the given workspace, keyed by current defaultAgent.
+     *
+     * Fix 4 (2026-07-18): 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.
+     */
+    private getRunner;
+    /** Update the config reference (call after `/config set` reloads). */
+    setConfig(config: AppConfig): void;
+    /** Get the current runner for a workspace. Used by router for agent-specific commands (P3.2). */
+    getCurrentRunner(workspace: string): AgentRunner;
+    /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
+     *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
+     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
+    currentBinding(userId: string): AgentBinding;
+    /**
+     * Clear all cached runner instances. Call after config changes that affect runner config.
+     */
+    clearRunners(): void;
+    /**
+     * Evict a (cwd, agentKind) runner cache slot. Unregisters the runner from the
+     * process-level exit dispatcher first (P1-1: without removal the singleton
+     * Set<Runner> retains every historical runner instance, so memory still grows
+     * with run count), then deletes the slot. Every runner-discarding path
+     * (clearRunners / finalizeRun / interruptCurrentRun) must go through this.
+     */
+    private evictRunnerSlot;
+    /**
+     * Update the idle watchdog window at runtime.
+     * Called by router constructor and `config.save` (when `idle.watchdogMinutes` changes
+     * via `/config` card). The idle interval reads `this.idleTimeoutMs` live on every
+     * tick, so the new threshold takes effect immediately for any in-flight run —
+     * there is no per-event timer to reset.
+     */
+    setIdleTimeout(ms: number): void;
+    /**
+     * Extract agent-specific run options from config.
+     * Returns model/effort/etc. based on current defaultAgent.
+     */
+    private getAgentRunOptions;
+    /**
+     * Enqueue a task into the workspace-level serial bridge queue.
+     * Delegates to QueueManager for actual implementation.
+     */
+    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;
+    /** Get queue info for a workspace. */
+    getQueueInfo(workspace: string): {
+        position: number;
+        tasksAhead: number;
+        isRunning: boolean;
+    };
+    /** Remove a task from the queue by messageId. Returns true if found and removed. */
+    removeFromQueue(workspace: string, messageId: string): boolean;
+    /**
+     * One-shot: replace the execution closure of an existing queued task in
+     * place, preserving its queue position. Used by queue.immediate after the
+     * user edits a queued message (see router handleQueueImmediate).
+     */
+    setTaskReplacement(workspace: string, messageId: string, task: () => Promise<void>): void;
+    /** Update queue card to "cancelled" status when user clicks 撤销. */
+    updateQueueCardToCancelled(workspace: string, messageId: string): Promise<void>;
+    /** Mark a queued task's card as executing immediately (grey out buttons).
+     *  Called by handleQueueImmediate so the user sees feedback right away
+     *  instead of waiting for the queue callback. Idempotent: the queue
+     *  callback's own updateQueueCardToExecuting call becomes a no-op because
+     *  updateQueueCardToExecuting deletes the card-message mapping in finally. */
+    markQueueCardExecuting(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 and has not
+     * settled yet. Lets handleQueueImmediate's final feedback distinguish a
+     * target that was cancelled from one that began while the interrupt was in
+     * flight (the latter is already running, so the toast must not claim
+     * "未安排执行").
+     */
+    hasTaskBegan(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 and build the updated queue
+     * card. Returns the card object to send back as the cardAction callback
+     * response (Feishu renders it in place), or null if the task is no longer
+     * queued. Returning the card via the callback response avoids the
+     * PATCH-vs-callback-response race that left the card stuck in edit state.
+     */
+    updateMessagePreview(workspace: string, messageId: string, newMessage: string): Promise<object | null>;
+    /** Whether a claude run is currently in progress in the given workspace. */
+    isBusyFor(workspace: string): boolean;
+    getActiveRunFor(workspace: string): ActiveRunSnapshot | undefined;
+    /** Whether any claude run is currently in progress (any workspace). */
+    get isBusy(): boolean;
+    /** Get all active runs across all workspaces. */
+    getAllActiveRuns(): Map<string, {
+        runId: string;
+        userId: string;
+        chatId: string;
+        cwd: string;
+    }>;
+    /** Get all active runs with their state for /active command (memory-based). */
+    getActiveRuns(): Array<{
+        runId: string;
+        sessionId: string;
+        cwd: string;
+        userId: string;
+        chatId: string;
+        terminal: RunTerminal;
+    }>;
+    /** Get all active bash runs with their state for /active command. */
+    getActiveBashRuns(): Array<{
+        runId: string;
+        cwd: string;
+        userId: string;
+        chatId: string;
+        terminal: RunTerminal;
+        command: string;
+    }>;
+    interruptCurrentRun(input: {
+        userId: string;
+        chatId: string;
+        runId?: string;
+        /** Restrict the match to a single workspace (queue.immediate). When
+         * omitted, all workspaces are candidates (used by /stop, /t, and card stop button which don't know which workspace to target). */
+        workspace?: string;
+    }): Promise<boolean>;
+    /** Send a result message to the user (§7). Returns true on success, false on failure. */
+    sendResult(result: BridgeResult, ctx: BridgeContext): Promise<boolean>;
+    /**
+     * Update an existing card in place (原地更新) instead of sending a new one.
+     *
+     * Used by /config cardAction handlers (config.toggle/set/input/save) so the
+     * user sees the card refresh on the same message bubble rather than getting
+     * a new card per click — same-message-bubble update pattern.
+     *
+     * Falls back to `sendResult` (which sends a new card as reply) when:
+     *   - `messageId` is missing (caller didn't pass ctx.messageId)
+     *   - `connector.updateCard` throws (card was deleted, network error, etc.)
+     *
+     * Returns true if the in-place update succeeded, false if it fell back.
+     */
+    updateCardInPlace(card: object, ctx: BridgeContext): Promise<boolean>;
+    /** Send a file to the user via Feishu. */
+    sendFile(filePath: string, ctx: BridgeContext): Promise<void>;
+    /** Reconnect the underlying Feishu channel. */
+    reconnect(): Promise<void>;
+    /**
+     * Resolve the working directory for a user.
+     * First checks sessionStore (set by /cd), then falls back to first workspace.
+     * Returns undefined if no cwd is available.
+     */
+    private resolveCwd;
+    /**
+     * Forward a non-command message to claude.
+     *
+     * Watchdog (§9.12): if no AgentEvent arrives within IDLE_TIMEOUT_MS, the
+     * run is considered hung and `runner.stop()` is called to unblock the
+     * work queue. Session is synced from `system.init`; every renderable event
+     * updates the same run card, and terminal events finalize that card.
+     */
+    forwardToClaude(message: string, ctx: BridgeContext, opts?: {
+        cwdOverride?: string;
+        binding?: AgentBinding;
+    }): Promise<void>;
+    /**
+     * Step 1 of forwardToClaude: Create run session components.
+     * Returns runId, cardSession, and activeRun object for tracking.
+     */
+    private createRunSession;
+    /**
+     * Step 2 of forwardToClaude: Run the agent and consume its event stream.
+     * Handles idle watchdog, event processing, session sync, and state transitions.
+     */
+    private runAgentStreamToEnd;
+    /**
+     * Step 3 of forwardToClaude: Finalize the run.
+     * Handles fallback card sending, completion notification, and cleanup.
+     */
+    private finalizeRun;
+    /**
+     * Read final usage (contextLength + compactCount + cache tokens) from the session jsonl.
+     * Called after a run finishes: live stream-json does not emit compact_boundary,
+     * so the live contextLength (fallback to result.usage input+output) is
+     * unreliable. The jsonl is authoritative for postTokens + compact event count.
+     */
+    private resolveFinalUsage;
+    /**
+     * Send a notification card when a run completes.
+     * This card contains the session summary and a button to resume the session.
+     * It's sent as a new message (not updating the run card) so users can easily
+     * find and return to this session without scrolling up.
+     */
+    private sendCompletionNotificationCard;
+    /**
+     * 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`.
+     */
+    executeBash(command: string, ctx: BridgeContext): Promise<void>;
+    /**
+     * Internal execution of bash command (called directly from executeBash,
+     * bypassing the serial queue — see executeBash).
+     */
+    private executeBashInternal;
+}
+export {};