lark-remote 0.4.4 → 0.5.0

package/dist/router/index.d.ts

@@ -1,21 +1,9 @@
 import type { SessionStore, SessionReaderRegistry } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
-import type { Bridge } from '../bridge/index.js';
+import type { Bridge, CommandContext, CommandResult } from '../bridge/index.js';
 import type { AgentBinding } from '../bridge/queue-manager.js';
 import type { CloneSession } from '../clone.js';
 import { type VersionCheckResult, type InstallResult } from '../update/index.js';
-interface CommandContext {
-    userId: string;
-    chatId: string;
-    messageId: string;
-    /** 本轮（装配窗口）全部入站 messageId，`messageId` 是最后一条。见 BridgeContext 同名字段（§B8）。 */
-    turnMessageIds?: string[];
-}
-interface CommandResult {
-    text?: string;
-    markdown?: string;
-    card?: object;
-}
 /**
  * Card-action commands that must run with enqueue({ immediate: true }).
  * These bypass the serial queue and execute immediately.
@@ -31,7 +19,7 @@ interface CommandResult {
  * stop        — interrupt current run
  * ls.file     — send file only
  * ws.page     — paginate /ws list only
- * ws.remove   — delete workspace alias only
+ * ws.remove   — delete cwd alias only
  * resume.use  — set sessionId + agent for correct reader routing
  * help.*      — read-only help commands
  * order.delete — delete order only
@@ -46,8 +34,8 @@ export interface CardActionPayload {
     name?: string;
     runId?: string;
     sessionId?: string;
+    /** 目标工作目录（queue.* 卡片动作定位队列；stop 等卡片回传执行目录）。 */
     cwd?: string;
-    workspace?: string;
     messageId?: string;
     userId?: string;
     chatId?: string;
@@ -56,7 +44,7 @@ export interface CardActionPayload {
     offset?: number;
     /**
      * `/ls` 浏览起点（本次 `/ls <dir>` 指定的目录；省略时 = cwd）。
-     * 卡片上的「返回」按钮回到这里，而不是回到 workspace cwd。
+     * 卡片上的「返回」按钮回到这里，而不是回到会话工作目录。
      */
     root?: string;
     /** /resume 列表的 agent 类型。 */
@@ -114,6 +102,18 @@ export declare const APPROVAL_ACTION_CMDS: readonly string[];
  * index.ts 控制层直返清单的唯一来源（勿在别处复制名单）。
  */
 export declare const DIRECT_RETURN_CMDS: ReadonlySet<string>;
+/**
+ * 会话 / cwd / agent 变更类卡片动作（单源）。这些动作会改写 sessionStore 的
+ * sessionId / cwd / defaultAgent，必须与入站装配器的 700ms 静默窗口定序：
+ * 控制层（index.ts）在执行它们之前先 flush 该 user/chat 的装配窗口，保证窗口内
+ * 先到的文本消息在本动作之前 commit（绑定动作前的旧状态）。否则窗口内消息会
+ * 漂移到动作之后的新状态（2026-10-07 事故：输入「重新构建」后立即点「新会话」，
+ * 消息落到新会话）。
+ *
+ * 文本命令（/new、/cd、/resume、/config）已由 index.ts 命令分支先 flush，
+ * 不在此列——只有卡片动作绕过了该分支。
+ */
+export declare const SESSION_MUTATING_ACTION_CMDS: ReadonlySet<string>;
 export declare class CommandRouter {
     /** Valid agent kinds — single source of truth for resume.use / resume.page / cmdResume. */
     static readonly VALID_AGENTS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
@@ -205,7 +205,7 @@ export declare class CommandRouter {
                 cachePath?: string;
                 bypassCache?: boolean;
             }) => Promise<VersionCheckResult>;
-            isNewer?: (current: string, latest: string) => boolean | null;
+            compareVersions?: (current: string, latest: string) => -1 | 0 | 1 | null;
             runInstallLatest?: () => Promise<InstallResult>;
         };
     });
@@ -222,7 +222,7 @@ export declare class CommandRouter {
     /**
      * Route a message: if it starts with /, handle as command; if it starts with !, execute as bash; otherwise forward to Claude.
      *
-     * 命令识别前置条件（2026-09-15 P0 修复）：
+     * 命令识别前置条件（2026-09-15修复，`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -249,7 +249,7 @@ export declare class CommandRouter {
      * Routes to the appropriate bridge method based on value.cmd.
      * Returns a toast response for immediate user feedback.
      */
-    /** queue.* 卡片动作通用守卫：workspace/messageId 缺失时回复错误并返回 null。 */
+    /** queue.* 卡片动作通用守卫：cwd/messageId 缺失时回复错误并返回 null。 */
     private queuePayloadOrReply;
     /** 答案类操作的统一失败反馈：重复投递（同一 nonce 第二次点击）是已生效的
      *  中性事件，报 error 会误导（首次点击实际已成功）。 */
@@ -304,7 +304,7 @@ export declare class CommandRouter {
      *
      * offset 恒重置为 0（新筛选从第 1 页开始）。路径校验与 TOCTOU 兜底照
      * handleLsPage——校验失败只回错误 toast，绝不动卡片（否则用户看到一张空卡）。
-     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选（设计文档 §2.3）。
+     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选。
      */
     private handleLsFilter;
     /**
@@ -350,17 +350,17 @@ export declare class CommandRouter {
         internalKey: string;
     } | null;
     /**
-     * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
      * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
     private rebuildListCard;
     /**
-     * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
+     * 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
      * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     private refreshListCard;
     /**
-     * W2.8 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
+     * 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
      * 的公共骨架——校验 orderId → reload+find → mutate → 成功后 toast + raw 卡。
      * mutate 返回 error 时仅回 error toast，不重渲染。
      * 注意：本 helper 只服务「toast + card 进响应体」语义（飞书需用响应体原地
@@ -410,7 +410,7 @@ export declare class CommandRouter {
      */
     private handleOrderTextInput;
     /**
-     * Handle ws.use card action: switch to the workspace, then refresh the /ws
+     * Handle ws.use card action: switch to the cwd, then refresh the /ws
      * list card in place so "recent" sort order is immediately visible.
      *
      * Unlike the command-line `/ws use` (which returns text), the card action
@@ -419,7 +419,7 @@ export declare class CommandRouter {
      */
     private handleWsUse;
     /**
-     * Handle ws.remove: remove the workspace alias and refresh the /ws list card
+     * Handle ws.remove: remove the cwd alias and refresh the /ws list card
      * in place (mirrors handleOrderDelete). Without this the stale alias would
      * remain visible on the card the user just clicked.
      */
@@ -472,7 +472,7 @@ export declare class CommandRouter {
     setNestedValue(target: AppConfig, key: string, value: unknown): void;
     diffConfig(original: AppConfig, pending: AppConfig): Record<string, string | undefined>;
     /**
-     * config 写盘后的运行时传播（P1-6：自 config.save 卡片路径抽出，卡片保存与
+     * config 写盘后的运行时传播（自 config.save 卡片路径抽出，卡片保存与
      * `/config <key> <value>` 文本直写两条路径共用）。
      *
      * 1. bridge 运行时值同步：setConfig + idle watchdog timeout；
@@ -480,7 +480,7 @@ export declare class CommandRouter {
      *    配置值，/status 与真实 run 自相矛盾）；
      * 3. defaultAgent 切换 → 旧 agent session 存 previousSessions、新 agent 恢复
      *    或清空（等效 /new）；
-     * 4. 当前 agent 配置变更 → syncAgentChoices 并原子写盘（P1-7：禁裸同步写盘，
+     * 4. 当前 agent 配置变更 → syncAgentChoices 并原子写盘（禁裸同步写盘，
      *    写一半崩溃会截断 config.yaml 导致 bridge 起不来）。
      *
      * @param updates 以 config 路径形式给出的变更 key（卡片路径来自 diffConfig；
@@ -530,7 +530,7 @@ export declare class CommandRouter {
     private buildConfigSwitchCard;
     /**
      * Whether a session of the given agent kind can be compacted from a resume
-     * card. Design doc §6.2-2: duck-typing — check if the runner has `runCompact`
+     * card. duck-typing — check if the runner has `runCompact`
      * (codex app-server, kimi acp), instead of hardcoding agentKind === 'codex'.
      */
     private canCompactSession;
@@ -556,7 +556,7 @@ export declare class CommandRouter {
      * @param offset  分页起点（条目数）
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
-     *                丢回 workspace cwd（用户明确反馈过）。
+     *                丢回 工作目录（用户明确反馈过）。
      * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
      *                省略/空 = 无筛选。
      */
@@ -584,7 +584,7 @@ export declare class CommandRouter {
      */
     cmdWs(args: string[], ctx: CommandContext, offset?: number, q?: string): CommandResult;
     /**
-     * L3: degraded card when a session's export is non-empty but unparseable
+     * degraded card when a session's export is non-empty but unparseable
      * (truncated by opencode's pipe cap on huge sessions, or otherwise corrupt).
      * The session exists, so reuse listSessions metadata (title) instead of the
      * misleading "未找到". Reuses the same card-builder helpers (markdownDiv) as