lark-remote 0.4.4 → 0.5.0

package/dist/bridge/index.d.ts

@@ -28,20 +28,20 @@ interface BridgeChannel extends RunCardChannel {
     addReaction(messageId: string, emoji: string): Promise<void>;
     removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
 }
-/** Caller context for a bridge operation. */
-interface BridgeContext {
+/** Caller context shared by bridge operations and router command handling. */
+export interface CommandContext {
     userId: string;
     chatId: string;
     messageId: string;
     /**
      * 本轮（装配窗口）全部入站 messageId，`messageId` 是其中最后一条。
      * 只有走入站装配器的路径会填；卡片动作等单消息路径留空，收尾退化为只处理
-     * `messageId`。缺它会导致合并轮次里先到的消息挂着 Typing 不撤（§B8）。
+     * `messageId`。缺它会导致合并轮次里先到的消息挂着 Typing 不撤。
      */
     turnMessageIds?: string[];
 }
-/** A sendable result payload (mirror of the router's CommandResult shape). */
-interface BridgeResult {
+/** A sendable result payload returned by a command handler. */
+export interface CommandResult {
     text?: string;
     markdown?: string;
     card?: object;
@@ -74,7 +74,7 @@ interface BridgeDeps {
     /** Override the idle watchdog timeout (default 15 min). Tests use a small value. */
     idleTimeoutMs?: number;
     /**
-     * Multi-agent registry. `getRunner(workspace)` looks up
+     * Multi-agent registry. `getRunner(cwd)` looks up
      * `config.defaultAgent` here.
      */
     agentRegistry: AgentRegistry;
@@ -91,10 +91,10 @@ interface BridgeDeps {
  *
  * 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
+ * cwd by `enqueue`: each cwd has its own Promise chain, so at
+ * most one agent process runs per cwd 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
+ * invariant — concurrent spawns within one cwd would corrupt session
  * state. Most card actions go through `enqueueImmediate` (fire-and-forget,
  * outside the serial chain); only run-forwarding is serialized.
  *
@@ -127,8 +127,8 @@ export declare class Bridge {
      */
     private runners;
     /**
-     * Runner 槽位在「活跃运行期间配置变更」时被标 stale（CC-06/P1）：clearRunners() 对
-     * 活跃 workspace 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
+     * Runner 槽位在「活跃运行期间配置变更」时被标 stale：clearRunners() 对
+     * 活跃 cwd 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
      * finalizeRun 安全 evict+dispose，下一轮 getRunner 创建新配置的 runner。
      * key 为 `${cwd}\u0000${agentKind}`。
      */
@@ -136,7 +136,7 @@ export declare class Bridge {
     /** Queue manager for per-workspace serial processing queue. */
     /** 普通消息队列管理器（public：测试注入 queue-card 状态用）。 */
     queueManager: QueueManager;
-    /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
+    /** Active runs per cwd (cwd). Multiple workspaces can run in parallel. */
     private activeRuns;
     /** Approval coordinators keyed by runId. */
     private approvalCoordinators;
@@ -144,17 +144,17 @@ export declare class Bridge {
      * 最近一次已完成的、runner 有 runCompact 的 run（按 cwd）。run 结束后
      * activeRuns 已清空，Compact 需要它来校验 runId 并提供 sessionId。
      */
-    private lastCompactableCodexRun;
+    private lastCompactableRun;
     /**
      * 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
+     * cwd, 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.
+     * 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
      * creates a NEW runner under a different key without evicting the old one.
@@ -174,17 +174,17 @@ export declare class Bridge {
     syncActiveApprovalModes(): void;
     /** Per-agent approval-mode settings snapshot from the current config. */
     private approvalModeSettingsFor;
-    /** Get the current runner for a workspace. Used by router for agent-specific commands (P3.2). */
-    getCurrentRunner(workspace: string): AgentRunner;
+    /** Get the current runner for a cwd. Used by router for agent-specific commands (.2). */
+    getCurrentRunner(cwd: string): AgentRunner;
     /**
      * Whether the runner for the given agent kind has runCompact capability.
-     * Used by router for compact button gating (design doc §6.2-2: duck-typing
+     * Used by router for compact button gating (duck-typing
      * instead of hardcoding agentKind === 'codex').
      */
-    hasRunCompact(workspace: string, kind?: AgentKind): boolean;
+    hasRunCompact(cwd: string, kind?: AgentKind): boolean;
     /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
-     *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
-     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
+     *  唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
+     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移。 */
     currentBinding(userId: string): AgentBinding;
     /**
      * Clear all cached runner instances. Call after config changes that affect runner config.
@@ -192,7 +192,7 @@ export declare class Bridge {
     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
+     * process-level exit dispatcher first (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.
@@ -221,36 +221,36 @@ export declare class Bridge {
      * 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;
+    enqueue(cwd: 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): {
+    enqueueImmediate(cwd: string, task: () => Promise<void>): void;
+    /** Get queue info for a cwd. */
+    getQueueInfo(cwd: 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;
+    removeFromQueue(cwd: 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;
+    setTaskReplacement(cwd: string, messageId: string, task: () => Promise<void>): void;
     /** Update queue card to "cancelled" status when user clicks 撤销. */
-    updateQueueCardToCancelled(workspace: string, messageId: string): Promise<void>;
+    updateQueueCardToCancelled(cwd: 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>;
+    markQueueCardExecuting(cwd: string, messageId: string): Promise<void>;
     /** Get task metadata from queue. */
-    getQueuedTask(workspace: string, messageId: string): QueuedTask | undefined;
+    getQueuedTask(cwd: 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
@@ -259,8 +259,8 @@ export declare class Bridge {
      * "未安排执行").
      */
     hasTaskBegan(messageId: string): boolean;
-    /** Get all queued tasks for a workspace. Returns a copy to prevent aliasing bugs. */
-    getQueuedTasks(workspace: string): QueuedTask[];
+    /** Get all queued tasks for a cwd. Returns a copy to prevent aliasing bugs. */
+    getQueuedTasks(cwd: 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
@@ -268,11 +268,11 @@ export declare class Bridge {
      * 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). */
+    updateMessagePreview(cwd: string, messageId: string, newMessage: string): Promise<object | null>;
+    /** Whether a claude run is currently in progress in the given cwd. */
+    isBusyFor(cwd: string): boolean;
+    getActiveRunFor(cwd: string): ActiveRunSnapshot | undefined;
+    /** Whether any claude run is currently in progress (any cwd). */
     get isBusy(): boolean;
     /** Get all active runs across all workspaces. */
     getAllActiveRuns(): Map<string, {
@@ -303,12 +303,12 @@ export declare class Bridge {
         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;
+        /** 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>;
     /** Send a result message to the user (§7). Returns true on success, false on failure. */
-    sendResult(result: BridgeResult, ctx: BridgeContext): Promise<boolean>;
+    sendResult(result: CommandResult, ctx: CommandContext): Promise<boolean>;
     /**
      * Update an existing card in place (原地更新) instead of sending a new one.
      *
@@ -322,9 +322,9 @@ export declare class Bridge {
      *
      * Returns true if the in-place update succeeded, false if it fell back.
      */
-    updateCardInPlace(card: object, ctx: BridgeContext): Promise<boolean>;
+    updateCardInPlace(card: object, ctx: CommandContext): Promise<boolean>;
     /** Send a file to the user via Feishu. */
-    sendFile(filePath: string, ctx: BridgeContext): Promise<void>;
+    sendFile(filePath: string, ctx: CommandContext): Promise<void>;
     /**
      * 入站媒体落盘（connector 下载完成后调用）：只落盘并回报结果，
      * 时间语义与回执由 `InboundTurnAssembler` 统一负责。
@@ -332,7 +332,7 @@ export declare class Bridge {
     saveInboundMedia(payload: InboundMediaPayload): Promise<MediaOutcome>;
     /**
      * Resolve the working directory for a user.
-     * First checks sessionStore (set by /cd), then falls back to first workspace.
+     * First checks sessionStore (set by /cd), then falls back to first cwd.
      * Returns undefined if no cwd is available.
      */
     private resolveCwd;
@@ -344,7 +344,7 @@ export declare class Bridge {
      * 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?: {
+    forwardToClaude(message: string, ctx: CommandContext, opts?: {
         cwdOverride?: string;
         binding?: AgentBinding;
     }): Promise<void>;
@@ -354,7 +354,7 @@ export declare class Bridge {
      */
     private createRunSession;
     /**
-     * §9.12 空闲看门狗：单 interval + 截止时间判定（P2-1），普通 run 与 compact
+     * §9.12 空闲看门狗：单 interval + 截止时间判定，普通 run 与 compact
      * 共用同一套兜底。事件到达只 `touch()` 刷新时间戳（无 timer 操作）；静默超过
      * `idleTimeoutMs` 才 finish('idle_timeout') + runner.stop()，让该工作区的串行
      * 队列继续推进（否则一个挂死的 run 永久堵住后续消息）。
@@ -443,7 +443,7 @@ export declare class Bridge {
         nonce: string;
     }): Promise<void>;
     /**
-     * Claude AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
      * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
      */
     handleApprovalAnswerCustom(opts: {
@@ -466,14 +466,14 @@ export declare class Bridge {
         nonce: string;
     }): Promise<void>;
     /**
-     * Handle codex.compact card action — trigger a compaction request for any
+     * Handle compact card action — trigger a compaction request for any
      * runCompact-capable runner（codex/kimi/opencode/pi/claude，按
-     * lastCompactableCodexRun 记录的 agentKind 路由）。Validates the run exists
+     * lastCompactableRun 记录的 agentKind 路由）。Validates the run exists
      * and is in a terminal state, then calls the runner's runCompact().
      */
-    handleCodexCompact(value: {
+    handleCompactAction(value: {
         runId?: string;
-    }, ctx: BridgeContext): Promise<void>;
+    }, ctx: CommandContext): Promise<void>;
     /**
      * §5.3: kimi 压缩在途检测——reader 鸭子实现 `readCompactionState` 时，若
      * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
@@ -485,18 +485,18 @@ export declare class Bridge {
      * 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 handleCodexCompact (run card button) and
+     * 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 streamCodexCompact;
+    private streamCompact;
     /**
      * Handle resume.compact card action — compact a session directly from a
      * resume card (auto-resume / `/resume <id>`), without a runId.
      *
-     * Unlike handleCodexCompact (which validates against the last finished run's
+     * 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.
@@ -504,14 +504,14 @@ export declare class Bridge {
     handleResumeCompact(value: {
         sessionId?: string;
         agent?: string;
-    }, ctx: BridgeContext): Promise<void>;
+    }, 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`.
      */
-    executeBash(command: string, ctx: BridgeContext): Promise<void>;
+    executeBash(command: string, ctx: CommandContext): Promise<void>;
     /**
      * Internal execution of bash command (called directly from executeBash,
      * bypassing the serial queue — see executeBash).