lark-remote 0.5.13 → 0.5.14

package/dist/connector/index.js

@@ -33,9 +33,9 @@ const noKeepAliveAgent = new https.Agent({ keepAlive: false });
  * - SDK 的 cardAction dedup eventId = `card:{messageId}:{operator.openId}:{actionId}`
  * - actionId = `tag|name|option|JSON.stringify(value)`，不含时间戳/事件序号
  * - config 卡片原地更新（updateCardInPlace），用户在同一张卡上重复触发
- *   固定 value 的按钮（如 config.toggle）：
+ *   固定 value 的按钮（如 config.save）：
  *   messageId / operator / value 三段都相同 → eventId 完全相同 → 第二次点击被
- *   seenCache drop，toggle 不可逆（第二次点击静默失效）。
+ *   seenCache drop，按钮不可逆（第二次点击静默失效）。
  *
  * SDK 默认 12h 太长；60s 仍会误伤连击。300ms 挡飞书瞬时重投递（<100ms 级），
  * 放过用户连击（慢点两次通常 >500ms）。代价：削弱 message 秒级重投递防护——
@@ -520,7 +520,7 @@ export class FeishuConnector {
         catch (err) {
             // 抛出去前先落一条格式化日志（调用方只看到包装后的 message）。
             // 抛普通 Error 而不是原 err：axios 错误对象跨层序列化会丢信息。
-            const errorInfo = this.formatError(err);
+            const errorInfo = formatErrorForLog(err);
             getLogger().error('[feishu] streamCard failed:', errorInfo);
             throw new Error(`streamCard failed: ${errorInfo}`, { cause: err });
         }
@@ -554,7 +554,7 @@ export class FeishuConnector {
         catch (err) {
             // Log the error but don't swallow it - a plain error avoids axios
             // serialization issues in the logger.
-            const errorInfo = this.formatError(err);
+            const errorInfo = formatErrorForLog(err);
             getLogger().error('[feishu] updateCard failed:', errorInfo);
             throw new Error(`updateCard failed: ${errorInfo}`, { cause: err });
         }
@@ -562,16 +562,12 @@ export class FeishuConnector {
             throw new Error(`updateCard failed: Feishu rejected the card (code=${rejection.code} msg=${rejection.msg ?? ''})`, { cause: rejection });
         }
     }
-    /** Format error for logging without causing circular serialization */
-    formatError(err) {
-        return formatErrorForLog(err);
-    }
     async addReaction(messageId, emoji) {
         try {
             await this.channel.addReaction(messageId, emoji);
         }
         catch (err) {
-            getLogger().error('[feishu] addReaction failed:', this.formatError(err));
+            getLogger().error('[feishu] addReaction failed:', formatErrorForLog(err));
         }
     }
     /**
@@ -583,7 +579,7 @@ export class FeishuConnector {
             await this.channel.removeReactionByEmoji(messageId, emoji);
         }
         catch (err) {
-            getLogger().error('[feishu] removeReactionByEmoji failed:', this.formatError(err));
+            getLogger().error('[feishu] removeReactionByEmoji failed:', formatErrorForLog(err));
         }
     }
     /**
@@ -635,7 +631,7 @@ export class FeishuConnector {
             }
         }
         catch (err) {
-            const errorInfo = this.formatError(err);
+            const errorInfo = formatErrorForLog(err);
             getLogger().error(`[feishu] ${label} failed:`, errorInfo);
             throw new Error(`${label} failed: ${errorInfo}`, { cause: err });
         }

package/dist/{runner/dsh → dsh}/auth.js

@@ -12,7 +12,7 @@ import { createHash, createHmac } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
-import { isWin32 } from '../../platform/select.js';
+import { isWin32 } from '../platform/select.js';
 import { resolveDshHome } from './home.js';
 /** Credential record that owns the browser-cookie signing secret. */
 export const DSH_BROWSER_CREDENTIAL_KEY = 'client-connection/browser-session';

package/dist/dsh/protocol.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DSH 远程调用的线格式助手（中立层，runner 与 session 共用）。
+ *
+ * 这两个函数原先住在 `runner/dsh/client.ts`，于是 session/dsh 为了拼一个
+ * `args` 信封要 import 上层 runner —— 与 AgentSessionReader 同一类反向依赖。
+ */
+/** Extract the `token` query parameter from a pasted `dsh web` URL. */
+export declare function extractDshToken(raw: string | undefined): string;
+export declare function dshArgs(method: string, payload: unknown): Record<string, unknown>;

package/dist/dsh/protocol.js

@@ -0,0 +1,61 @@
+/**
+ * DSH 远程调用的线格式助手（中立层，runner 与 session 共用）。
+ *
+ * 这两个函数原先住在 `runner/dsh/client.ts`，于是 session/dsh 为了拼一个
+ * `args` 信封要 import 上层 runner —— 与 AgentSessionReader 同一类反向依赖。
+ */
+/** Extract the `token` query parameter from a pasted `dsh web` URL. */
+export function extractDshToken(raw) {
+    const value = (raw ?? '').trim();
+    if (!value)
+        return '';
+    if (!value.includes('token=') && !value.includes('://'))
+        return value;
+    try {
+        const url = new URL(value.startsWith('?') ? `http://dsh.invalid/${value}` : value);
+        const token = url.searchParams.get('token');
+        if (token)
+            return token;
+        // 带 scheme 却没有 token 参数的输入是误贴的 host URL（如
+        // `http://127.0.0.1:3080`）：整串不是合法 token，参与握手只会得到
+        // 指向性缺失的 401。返回空串让上游走「token 缺失」的诊断路径。
+        if (value.includes('://'))
+            return '';
+        return value;
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Remote methods take named parameters. Most session methods call their single
+ * argument `request`; `session/list` reserves `_request`; catalog methods take
+ * no arguments. `commands/*` address the receiving agent by its wire field
+ * `agentId`, so their payload is already in wire shape (pass-through).
+ * The gateway rejects any other `args` shape.
+ */
+const DSH_ARGS_KEY = {
+    'session/list': '_request',
+    'session/create': 'request',
+    'session/prompt': 'request',
+    'session/cancel': 'request',
+    'session/selectModel': 'request',
+    'session/projections': 'request',
+    'session/page': 'request',
+    'session/follow': 'request',
+    'session/updateQueue': 'request',
+    'job/list': 'request',
+    'job/kill': 'request',
+    'session/modelCatalog': null,
+    'agentPresets/list': null,
+    'permissionPresets/catalog': null,
+};
+export function dshArgs(method, payload) {
+    const key = DSH_ARGS_KEY[method];
+    if (key === null)
+        return {};
+    if (key === undefined)
+        return payload;
+    return { [key]: payload };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/index.js

@@ -1,5 +1,5 @@
 import { loadConfig, getAgentConfig } from './config/index.js';
-import { resolveAgentChoices, } from './runner/index.js';
+import { resolveAgentChoices } from './runner/index.js';
 import { ensureConfig } from './config/wizard.js';
 import { parseCliArgs, resolveConfigDir, setConfigDir, printHelp, printVersion, } from './config/dir.js';
 import { FeishuConnector } from './connector/index.js';
@@ -25,7 +25,7 @@ import { startSleepBlocker } from './platform/sleep-blocker.js';
 import { checkLatestVersion, compareVersions, runInstallLatest, formatUpdateHint, } from './update/index.js';
 import { classifyRejection } from './error-classification.js';
 import { WorkspaceStore } from './workspace/index.js';
-import { buildSessionHistoryCard, pickResumeCardEvents } from './router/card-helpers.js';
+import { buildSessionHistoryCard, pickResumeCardEvents } from './card/card-helpers.js';
 import { newSessionButton, resumeCompactButton, agentDisplayName } from './card/card-shared.js';
 import path from 'node:path';
 import { setupMessageHandlers } from './message-handlers.js';
@@ -137,6 +137,10 @@ function initializeRunner(config, configDir, cliArgs) {
         manageProcess: () => getAgentConfig(latest(), 'dsh')?.manageProcess ?? true,
         startTimeoutMs: () => getAgentConfig(latest(), 'dsh')?.startTimeoutMs,
     });
+    // claude 的会话读取器与其余 agent 一样由组合根注入：runner 侧不 import session
+    // 层（否则 runner ↔ session 互相依赖），且 bridge 读 usage / router 列 session
+    // 用的是同一个实例（缓存共用）。
+    const claudeSessionReader = new ClaudeSessionReader();
     // Claude factory reads from configContainer (not closure) so runtime
     // config changes (model, effort, stopGraceMs) take effect after
     // bridge.setConfig() + clearRunners(). Same pattern as codex/pi/kimi.
@@ -149,6 +153,7 @@ function initializeRunner(config, configDir, cliArgs) {
             settings: cliArgs.settings,
             pidDir: configDir,
             cwd: ws,
+            sessionReader: claudeSessionReader,
             permissionMode: claudeConfig.permissionMode,
             idleTtlMs: claudeConfig.idleTtlMinutes != null ? claudeConfig.idleTtlMinutes * 60_000 : undefined,
         });
@@ -179,7 +184,7 @@ function initializeRunner(config, configDir, cliArgs) {
     // Register OpencodeAcpRunner (pure ACP mode, `opencode acp` JSON-RPC over stdio)
     // Register session reader (same instance as used by runner)
     const sessionReaderRegistry = new SessionReaderRegistry();
-    sessionReaderRegistry.register('claude', new ClaudeSessionReader());
+    sessionReaderRegistry.register('claude', claudeSessionReader);
     sessionReaderRegistry.register('codex', codexSessionReader);
     // Register OpencodeSessionReader (CLI version)
     // Using `opencode session list` and `session export` instead of HTTP API.
@@ -436,8 +441,8 @@ async function main() {
     try {
         await connector.connect();
     }
-    catch {
-        logger.error('failed to connect to Feishu, check appId/appSecret');
+    catch (err) {
+        logger.error('failed to connect to Feishu, check appId/appSecret:', err);
         process.exit(1);
     }
     if (binder.isBound()) {

package/dist/model-catalog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Claude 模型 ID ↔ CLI alias 的双向表。
+ *
+ * 中立层（谁都不许反向依赖它）：config 要写默认值、runner/claude 要把 alias 传给
+ * CLI、router/config 要把 alias 显示给用户。此前这张表住在 config/，于是
+ * 「地基层被 runner 反向 import」；挪到这里后三方共同引用同一份。
+ *
+ * 表内容来自 Claude CLI 的模型别名（alias 是 CLI 侧的稳定名字，model ID 会随
+ * 版本变），新增一行只改这里。
+ */
+/** 模型 ID → alias 映射。 */
+export declare const MODEL_ID_TO_ALIAS: Record<string, string>;
+/** alias → model ID 反向映射。 */
+export declare const MODEL_ALIAS_TO_ID: Record<string, string>;

package/dist/model-catalog.js

@@ -0,0 +1,25 @@
+/**
+ * Claude 模型 ID ↔ CLI alias 的双向表。
+ *
+ * 中立层（谁都不许反向依赖它）：config 要写默认值、runner/claude 要把 alias 传给
+ * CLI、router/config 要把 alias 显示给用户。此前这张表住在 config/，于是
+ * 「地基层被 runner 反向 import」；挪到这里后三方共同引用同一份。
+ *
+ * 表内容来自 Claude CLI 的模型别名（alias 是 CLI 侧的稳定名字，model ID 会随
+ * 版本变），新增一行只改这里。
+ */
+/** 模型 ID → alias 映射。 */
+export const MODEL_ID_TO_ALIAS = {
+    'claude-opus-4-8': 'opus',
+    'claude-sonnet-4-6': 'sonnet',
+    'claude-haiku-4-5-20250501': 'haiku',
+    'claude-fable-5': 'fable',
+};
+/** alias → model ID 反向映射。 */
+export const MODEL_ALIAS_TO_ID = {
+    opus: 'claude-opus-4-8',
+    sonnet: 'claude-sonnet-4-6',
+    haiku: 'claude-haiku-4-5-20250501',
+    fable: 'claude-fable-5',
+};
+//# sourceMappingURL=model-catalog.js.map

package/dist/platform/path.d.ts

@@ -1,6 +1,15 @@
 export interface PathOptions {
     platform?: NodeJS.Platform;
 }
+/**
+ * realpath 归一（macOS `/tmp` → `/private/tmp`），失败回退原样输入。
+ *
+ * 各 session reader 此前有三种口径：静默回退（opencode）、回退 + warn（kimi
+ * 单会话读）、裸调让一次 ENOENT 把整张会话列表清掉（kimi list）。统一成
+ * 「回退优先于丢结果」，失败原因交给调用方记日志（`onFailure`），因为
+ * ENOENT（陈旧 cwd）是正常空态、EACCES/EBUSY 才需要留痕。
+ */
+export declare function safeRealpath(cwd: string, onFailure?: (err: unknown) => void): string;
 /**
  * 路径的「判等键」形态：把 samePath 的平台归一规则单源化，供 Map/Set 键控
  * 场景使用（按 cwd 建倒排索引时不能每次查询做 O(n) 两两比较）。不变量：

package/dist/platform/path.js

@@ -9,8 +9,26 @@
  * 全部函数接受显式 `platform` 参数（默认 currentPlatform），使 win32 语义
  * 可在任意宿主的单元测试中验证。
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { currentPlatform, isWin32 } from './select.js';
+/**
+ * realpath 归一（macOS `/tmp` → `/private/tmp`），失败回退原样输入。
+ *
+ * 各 session reader 此前有三种口径：静默回退（opencode）、回退 + warn（kimi
+ * 单会话读）、裸调让一次 ENOENT 把整张会话列表清掉（kimi list）。统一成
+ * 「回退优先于丢结果」，失败原因交给调用方记日志（`onFailure`），因为
+ * ENOENT（陈旧 cwd）是正常空态、EACCES/EBUSY 才需要留痕。
+ */
+export function safeRealpath(cwd, onFailure) {
+    try {
+        return fs.realpathSync(cwd);
+    }
+    catch (err) {
+        onFailure?.(err);
+        return cwd;
+    }
+}
 function resolveOptions(opts) {
     return { platform: opts?.platform ?? currentPlatform };
 }

package/dist/router/active-run-usage.d.ts

@@ -0,0 +1,4 @@
+import type { ActiveRunSnapshot } from '../bridge/index.js';
+import type { SessionDisplayUsage } from '../card/usage-format.js';
+/** 从 bridge 的活跃 run 快照提取会话卡需要的用量字段。 */
+export declare function activeRunUsage(activeRun: ActiveRunSnapshot | undefined): SessionDisplayUsage | undefined;

package/dist/router/active-run-usage.js

@@ -0,0 +1,12 @@
+/** 从 bridge 的活跃 run 快照提取会话卡需要的用量字段。 */
+export function activeRunUsage(activeRun) {
+    if (!activeRun || activeRun.contextLength === undefined)
+        return undefined;
+    return {
+        contextLength: activeRun.contextLength,
+        compactCount: activeRun.compactCount,
+        cacheReadTokens: activeRun.cacheReadTokens,
+        cacheCreationTokens: activeRun.cacheCreationTokens,
+    };
+}
+//# sourceMappingURL=active-run-usage.js.map

package/dist/router/commands/ls.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { cardButton } from '../../card/card-shared.js';
-import { paginationBar, searchBar } from '../card-helpers.js';
+import { paginationBar, searchBar } from '../../card/card-helpers.js';
 import { inspectPath, statPath } from '../path-validation.js';
 import { pageSlice } from '../paging.js';
 export const LS_PAGE_SIZE = 30;

package/dist/router/commands/order.js

@@ -1,5 +1,5 @@
 import { cardButton } from '../../card/card-shared.js';
-import { paginationBar } from '../card-helpers.js';
+import { paginationBar } from '../../card/card-helpers.js';
 import { pageSlice } from '../paging.js';
 export const ORDER_PAGE_SIZE = 8;
 export function buildOrderCommand(args, ctx, offset, deps) {

package/dist/router/commands/resume.d.ts

@@ -1,11 +1,13 @@
 import type { CommandContext, CommandResult } from '../../bridge/index.js';
-import type { AgentKind, AgentSessionContentEvent, AgentSessionReader } from '../../runner/index.js';
-import type { SessionDisplayUsage } from '../usage-format.js';
+import type { AgentKind } from '../../agent-kinds.js';
+import type { AgentSessionContentEvent, AgentSessionReader } from '../../session-contract.js';
+import type { SessionDisplayUsage } from '../../card/usage-format.js';
 export declare const AUTO_RESUME_MAX_EVENTS = 5;
 export declare const RESUME_PAGE_SIZE = 5;
 interface ResumeSessionEntry {
     cwd?: string;
-    sessions?: Map<string, string>;
+    /** SessionStore 的 entry 恒有 sessions（`get()` 只会返回整条或缺席）。 */
+    sessions: Map<string, string>;
 }
 interface SessionDisplay {
     events: AgentSessionContentEvent[];
@@ -18,7 +20,6 @@ interface SessionDisplay {
 }
 export interface ResumeCommandDeps {
     defaultAgent: AgentKind;
-    validAgents: readonly AgentKind[];
     getSessionEntry(userId: string): ResumeSessionEntry | undefined;
     setSessionId(userId: string, agent: AgentKind, sessionId: string, cwd: string): void;
     defaultReader(): AgentSessionReader;

package/dist/router/commands/resume.js

@@ -1,5 +1,6 @@
+import { isAgentKind } from '../../agent-kinds.js';
 import { agentDisplayName } from '../../card/card-shared.js';
-import { buildSessionHistoryCard, paginationBar } from '../card-helpers.js';
+import { buildSessionHistoryCard, paginationBar } from '../../card/card-helpers.js';
 import { pageInfo } from '../paging.js';
 import { clampInt } from '../../common/clamp.js';
 export const AUTO_RESUME_MAX_EVENTS = 5;
@@ -14,12 +15,11 @@ function sessionPreviewLine(text, max) {
 export function buildResumeCommand(args, ctx, offset, deps) {
     const entry = deps.getSessionEntry(ctx.userId);
     const cwd = entry?.cwd;
-    const validAgents = deps.validAgents;
     let agentKind = deps.defaultAgent;
     let limit;
     let sessionIdArg;
     if (args[0]) {
-        if (validAgents.includes(args[0])) {
+        if (isAgentKind(args[0])) {
             agentKind = args[0];
             if (args[1]) {
                 if (/^\d+$/.test(args[1]))
@@ -149,7 +149,7 @@ export function buildResumeCommand(args, ctx, offset, deps) {
     const elements = [
         { tag: 'div', text: { tag: 'lark_md', content: `📂 当前工作目录：\`${cwd}\`` } },
     ];
-    const currentId = entry?.sessions?.get(agentKind) ?? '';
+    const currentId = entry.sessions.get(agentKind) ?? '';
     for (const session of allSessions) {
         const isCurrent = agentKind === deps.defaultAgent && session.sessionId === currentId;
         const meta = sessionMeta.get(session.sessionId);

package/dist/router/commands/ws.js

@@ -1,5 +1,5 @@
 import { cardButton } from '../../card/card-shared.js';
-import { paginationBar, searchBar } from '../card-helpers.js';
+import { paginationBar, searchBar } from '../../card/card-helpers.js';
 import { pageSlice } from '../paging.js';
 import { resolveDirectory } from '../path-validation.js';
 export const WS_PAGE_SIZE = 5;

package/dist/router/config/claude.js

@@ -4,7 +4,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { MODEL_ID_TO_ALIAS, MODEL_ALIAS_TO_ID, getModelOptionsFromSettings, CLAUDE_EFFORTS, CLAUDE_PERMISSION_MODES, } from '../../config/index.js';
+import { CLAUDE_EFFORTS, CLAUDE_PERMISSION_MODES, getModelOptionsFromSettings, } from '../../config/index.js';
+import { MODEL_ALIAS_TO_ID, MODEL_ID_TO_ALIAS } from '../../model-catalog.js';
 /** Claude 官方 --permission-mode 中文注释（value 走 CLAUDE_PERMISSION_MODES SSOT）。 */
 const PERMISSION_MODE_LABELS = {
     default: '默认（敏感操作逐项询问）',

package/dist/router/config/common/render.d.ts

@@ -1,8 +1,12 @@
 /**
  * Shared config card rendering logic.
  *
- * Builds CardKit 2.0 elements for config fields (boolean toggle, select dropdown, input).
+ * Builds CardKit 2.0 elements for config fields (select dropdown, input, note).
  * Used by all agent config builders and the shared tabs (idle, logging).
+ *
+ * 控件形态只有 `ConfigField.type` 里那三种，且每种在本文件都有对应 builder：
+ * 渲染端与处理端（router 的 `config.set` / `config.input`）必须一一对应，
+ * 「渲染得出按钮、点了没人处理」是禁止状态（守卫见 config-card-controls.test.ts）。
  */
 import { type AppConfig } from '../../../config/index.js';
 import type { ConfigField } from '../types.js';

package/dist/router/config/common/render.js

@@ -1,8 +1,12 @@
 /**
  * Shared config card rendering logic.
  *
- * Builds CardKit 2.0 elements for config fields (boolean toggle, select dropdown, input).
+ * Builds CardKit 2.0 elements for config fields (select dropdown, input, note).
  * Used by all agent config builders and the shared tabs (idle, logging).
+ *
+ * 控件形态只有 `ConfigField.type` 里那三种，且每种在本文件都有对应 builder：
+ * 渲染端与处理端（router 的 `config.set` / `config.input`）必须一一对应，
+ * 「渲染得出按钮、点了没人处理」是禁止状态（守卫见 config-card-controls.test.ts）。
  */
 import { getConfigValue } from '../../../config/index.js';
 import { cardButton } from '../../../card/card-shared.js';
@@ -12,12 +16,7 @@ function buildFieldElements(fields, displayConfig) {
     for (const field of fields) {
         // Get current value from displayConfig for dynamic fields
         const currentValue = getConfigValue(displayConfig, field.key);
-        if (field.type === 'boolean') {
-            // For boolean, use field.currentValue if set, otherwise use config value
-            const isOn = field.currentValue !== undefined ? field.currentValue === true : currentValue === true;
-            elements.push(buildBooleanElement(field, isOn));
-        }
-        else if (field.type === 'select' && field.options) {
+        if (field.type === 'select' && field.options) {
             elements.push(buildSelectElement(field, currentValue));
         }
         else if (field.type === 'note') {
@@ -53,12 +52,6 @@ function fieldRow(label, control) {
         ],
     };
 }
-function buildBooleanElement(field, isOn) {
-    const displayVal = isOn ? '✅ 已开启' : '⚪ 已关闭';
-    return fieldRow(field.label, cardButton(displayVal, { cmd: 'config.toggle', key: field.key }, {
-        type: isOn ? 'primary' : 'default',
-    }));
-}
 function buildSelectElement(field, currentValue) {
     // 优先使用 field.currentValue（卡片显示用覆盖值），否则使用 config 中的值
     const selectedValue = field.currentValue != null

package/dist/router/config/dsh.d.ts

@@ -17,7 +17,7 @@
  */
 import type { AgentConfigCardBuilder, ConfigField } from './types.js';
 import { type AppConfig } from '../../config/index.js';
-import type { DshModelCatalogValue, DshPermissionCatalogValue, DshPresetListValue } from '../../runner/dsh/types.js';
+import type { DshModelCatalogValue, DshPermissionCatalogValue, DshPresetListValue } from '../../dsh/types.js';
 /** DshConfigBuilder 预取只依赖的 client 方法子集。 */
 export interface DshCatalogClient {
     listModels(): Promise<DshModelCatalogValue>;

package/dist/router/config/index.d.ts

@@ -4,7 +4,7 @@
  * Each agent implements AgentConfigCardBuilder in its own file.
  * Adding a new agent = add a file + register here (no upstream changes needed).
  */
-import type { AgentKind } from '../../runner/types.js';
+import type { AgentKind } from '../../agent-kinds.js';
 import type { AgentConfigCardBuilder } from './types.js';
 /**
  * 首次启动默认展示的 Coding Agent 顺序：Codex → Claude → OpenCode → Pi → Kimi → DSH。

package/dist/router/config/types.d.ts

@@ -16,13 +16,21 @@ export interface SelectOption {
 export interface ConfigField {
     key: string;
     label: string;
-    type: 'boolean' | 'select' | 'input' | 'note';
+    /**
+     * 卡片上真实存在的控件形态，每种都在 `common/render.ts` 有对应 builder：
+     * select=下拉、input=文本框、note=纯说明行（无回调）。
+     *
+     * 没有 boolean：卡片曾留着一套「开关」控件（`config.toggle`），但全仓没有
+     * 任何字段声明它，2026-10-27 成套删除。原则是**卡片只放配得了的控件**，
+     * 实现细节与未上卡的键走 YAML（见 `buildConfigCard` 的分 tab 注释）。
+     */
+    type: 'select' | 'input' | 'note';
     /** For select type: the list of options shown in the dropdown.
      *  Accepts plain strings (text=value) or {text, value} objects for
      *  display-value separation (e.g. 'manual（逐项审批）' → value 'manual'). */
     options?: readonly (string | SelectOption)[];
     /** Override the currentValue shown in the card (takes priority over getConfigValue). */
-    currentValue?: string | boolean;
+    currentValue?: string;
 }
 /**
  * Builder that provides config fields and handles field changes for a specific agent.
@@ -40,7 +48,7 @@ export interface AgentConfigCardBuilder {
      * Handle a field change for this agent.
      *
      * @param key   - The field key (e.g. 'agents.codex.modelProvider')
-     * @param value - The new value (string for select/input, already toggled for boolean)
+     * @param value - The new value (string for select/input)
      * @param config - The current pendingConfig (read-only reference for deriving dependent values)
      * @returns An array of {key, value} patches to apply to pendingConfig.
      *          The caller (router) applies these via setNestedValue.

package/dist/router/index.d.ts

@@ -137,12 +137,6 @@ export declare const SESSION_MUTATING_ACTION_CMDS: ReadonlySet<string>;
  */
 export declare const COMPACT_ACTION_CMDS: ReadonlySet<string>;
 export declare class CommandRouter {
-    /**
-     * Valid agent kinds — single source of truth for resume.use / resume.page /
-     * cmdResume. 名单本体在 `runner/types.ts` 的 AGENT_KINDS（与 AgentKind 类型
-     * 同源），这里只做别名，避免人手抄第二份。
-     */
-    static readonly VALID_AGENTS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
     private sessionStore;
     /** 飞书桥接实例（public：测试直接访问断言，替代 as unknown as）。 */
     bridge: Bridge;
@@ -215,8 +209,8 @@ export declare class CommandRouter {
     /**
      * 串行化 config.* 卡片回调（2026-07-04）。
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，**不进串行队列**，
-     * 多次快速点击 toggle/input 会并发读写 `pendingConfig` 并同时调
-     * `updateCardInPlace` → Feishu API 乱序到达，导致 toggle 卡死在某个状态。
+     * 多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
+     * `updateCardInPlace` → Feishu API 乱序到达，控件卡死在某个状态。
      * 此 Promise chain 把所有 config.* 动作串成一个执行链，保证后到的动作
      * 等前一个动作的卡片 patch 完成后再读 `pendingConfig`。
      */
@@ -304,7 +298,37 @@ export declare class CommandRouter {
      * Handle queue.immediate: stop current run, clear queue before this message, execute this message immediately.
      * Instead of asking user to resend, we keep the target task in queue and let it execute.
      */
+    /**
+     * 把「执行编辑后的内容」注册成原队列槽位的一次性 replacement（复用入队时
+     * 捕获的 binding + 恢复 lane cwd，否则编辑后重跑的 run 会丢 cwd 与绑定）。
+     *
+     * 重新入队不行：`enqueue` 只能追加到 promise 链尾部，会把编辑任务甩到
+     * 后来者后面，违背「立即执行 = 下一个就跑」。三个调用点都必须在任何 await
+     * 之前注册——begin 路径消费 replacement 的时机不可预测（见
+     * handleQueueImmediate 步骤 1.5 的竞态说明）。
+     */
+    private registerEditedReplacement;
     private handleQueueImmediate;
+    /**
+     * 清掉排在目标之前的所有排队任务，返回实际清除条数。
+     *
+     * 两条红线：
+     * - 目标可能在 interruptCurrentRun 等待期间已经接跑（链并发前进），那时它已不在
+     *   快照里，剩下的全部排在它**后面**——清除必须在目标位置之前停下，不得越界删掉
+     *   用户没要求清除的任务。
+     * - 移除循环必须整体同步：队列链在任何 await 处都会推进（卡片 PATCH 也算），
+     *   一旦让出事件循环，用户要求清除的任务可能趁撤销卡还在路上就跑起来了。
+     *   撤销卡片由 `removeFromQueue` 统一触发（fire-and-forget）。
+     */
+    private clearTasksAheadOfTarget;
+    /**
+     * `queue.immediate` 的终态反馈（唯一出口）。
+     *
+     * 承诺必须与真实调度一致：目标只有确实是停止后的下一个，才可以把它的卡翻成
+     * 「执行中」并说「将立即执行」；在途接跑/被撤销/被抢先/远程停止未确认四种状态
+     * 各给各的文案（把没发生的事说成发生了，比沉默更糟——用户会据文案决定要不要重发）。
+     */
+    private reportImmediateOutcome;
     /**
      * Handle queue.diagnose: show diagnostic info for why message is queuing.
      */
@@ -514,6 +538,12 @@ export declare class CommandRouter {
      * 无 messageId 的调用（测试/文本路径）不登记。
      */
     private rememberConfigCard;
+    /**
+     * 把一次字段变更交给当前 agent 的 config builder（处理 provider→model 这类
+     * 依赖关系），逐条写进草稿，再把草稿刷到所有配置卡。
+     * `config.set`（下拉）与 `config.input`（输入框提交）共用同一套应用逻辑。
+     */
+    private applyConfigFieldChange;
     /**
      * 把当前草稿刷到所有已知 config 卡片上（含本次点击的那张）。
      *
@@ -523,12 +553,12 @@ export declare class CommandRouter {
      */
     private refreshConfigCards;
     /**
-     * 串行化 config.* 卡片回调（2026-07-04 修复 toggle 卡死 bug）。
+     * 串行化 config.* 卡片回调（2026-07-04 修复连击卡死 bug）。
      *
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，不进 bridge 的
-     * 串行队列；多次快速点击 toggle 会并发读写 `pendingConfig` 并同时调
+     * 串行队列；多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
      * `updateCardInPlace` → 两个 patch 请求乱序到达飞书，后到达的 patch（点击 1
-     * 的旧卡片）覆盖先到达的 patch（点击 2 的新卡片），用户看到 toggle 卡死。
+     * 的旧卡片）覆盖先到达的 patch（点击 2 的新卡片），用户看到控件卡死。
      *
      * 此方法把所有 config.* 动作串成一个 Promise chain：每个动作等前一个动作
      * 的 `updateCardInPlace` 完全 settle 后再读 `pendingConfig`。