lark-remote 0.1.12 → 0.2.0

package/dist/platform/terminator-posix.js

@@ -0,0 +1,103 @@
+import { getLogger } from '../logger/index.js';
+/** 默认日志出口：与迁移前同级别（debug 记信号，info 记 grace 超时）。 */
+function defaultLog(level, message) {
+    const logger = getLogger();
+    if (level === 'debug')
+        logger.debug(message);
+    else
+        logger.info(message);
+}
+/** 退出判定统一口径（CLAUDE.md 红线）：exitCode !== null || signalCode !== null。 */
+function isAlive(proc) {
+    return proc.exitCode === null && proc.signalCode === null;
+}
+async function stopPosix(proc, opts, log) {
+    if (!isAlive(proc)) {
+        return { requested: false, via: 'already-exited' };
+    }
+    const pid = proc.pid;
+    if (pid === undefined) {
+        return { requested: false, via: 'already-exited' };
+    }
+    // 负 PID = 整个进程组：shell 包装层与孙进程一并带走
+    const pgid = -pid;
+    log('debug', `[process-stopper] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
+    try {
+        process.kill(pgid, 'SIGTERM');
+    }
+    catch {
+        /* process may have exited */
+    }
+    if (opts.immediate) {
+        // 不等待：SIGKILL 紧随其后；进程已死时 kill 抛 ESRCH，忽略即可
+        try {
+            process.kill(pgid, 'SIGKILL');
+        }
+        catch {
+            /* process already gone */
+        }
+        return { requested: true, via: 'taskkill' };
+    }
+    // 与 exit 事件竞速等 grace；用 once 避免重复 stop() 累积监听器（P2-15）
+    let graceTimer;
+    const exited = await Promise.race([
+        new Promise((resolve) => {
+            if (!isAlive(proc))
+                return resolve(true);
+            proc.once('exit', () => resolve(true));
+        }),
+        new Promise((resolve) => {
+            graceTimer = setTimeout(() => resolve(false), opts.graceMs);
+        }),
+    ]);
+    if (graceTimer)
+        clearTimeout(graceTimer);
+    if (!exited) {
+        log('info', `[process-stopper] process group ${pgid} did not exit within grace period, sending SIGKILL`);
+        try {
+            process.kill(pgid, 'SIGKILL');
+        }
+        catch {
+            /* process already gone */
+        }
+        return { requested: true, via: 'taskkill' };
+    }
+    return { requested: true, via: 'cooperative' };
+}
+export function createPosixTerminator(deps) {
+    const log = deps.log ?? defaultLog;
+    return {
+        stop(proc, opts) {
+            return stopPosix(proc, { graceMs: deps.graceMs, immediate: opts.immediate }, log);
+        },
+        cleanupOnExit(proc) {
+            if (!isAlive(proc))
+                return;
+            const pid = proc.pid;
+            if (pid === undefined)
+                return;
+            try {
+                process.kill(-pid, 'SIGKILL');
+            }
+            catch {
+                /* process already gone */
+            }
+        },
+    };
+}
+/**
+ * 迁移前的类名（兼容壳）：返回 void、接受 null proc。
+ * 新代码请用 {@link createPosixTerminator} / `createTerminator`。
+ */
+export class ProcessStopper {
+    graceMs;
+    constructor(opts) {
+        this.graceMs = opts.graceMs;
+    }
+    async stop(proc, opts) {
+        if (!proc)
+            return;
+        await stopPosix(proc, { graceMs: this.graceMs, immediate: opts?.immediate === true }, defaultLog);
+    }
+}
+//# sourceMappingURL=terminator-posix.js.map

package/dist/platform/terminator-win32.d.ts

@@ -0,0 +1,21 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import type { Terminator } from './terminator.js';
+import { AgentStopperRegistry } from './agent-stopper.js';
+export type SpawnLike = (file: string, args: string[], opts?: SpawnOptions) => ChildProcess;
+/** 等待 graceMs 与 exit 事件竞速；返回 true 表示等待结束后进程仍存活。 */
+export type WaitForExit = (proc: ChildProcess, ms: number) => Promise<boolean>;
+export interface Win32TerminatorDeps {
+    /** 协议停止后的优雅等待窗口（毫秒），对应 posix 的 stopGraceMs */
+    graceMs: number;
+    /** 当前 run 所属 agent：用于查协议停止通道；缺省视为无通道 */
+    agent?: string;
+    /** 协议通道注册表注入（测试隔离）；默认进程级单例 */
+    stoppers?: AgentStopperRegistry;
+    /** spawn 注入（测试用）；默认 node:child_process */
+    spawn?: SpawnLike;
+    /** grace 等待器注入（测试用）；默认与 exit 事件竞速 */
+    waitForExit?: WaitForExit;
+    /** 日志注入：本模块处于 seam 底层，不反向依赖 logger 单例 */
+    log?: (message: string) => void;
+}
+export declare function createWin32Terminator(deps: Win32TerminatorDeps): Terminator;

package/dist/platform/terminator-win32.js

@@ -0,0 +1,110 @@
+/**
+ * win32 终止器：协议停止通道 → grace 等待 → taskkill 树杀（design.md §3.2）。
+ *
+ * 状态机：
+ *   1. 进程已退出 → nothing（via='already-exited'）
+ *   2. immediate  → taskkill /PID <pid> /T /F
+ *   3. 优雅       → AgentStopperRegistry 查协议通道
+ *      - 无通道：打日志显式跳过优雅段（不等一个不会来的退出事件）→ 直接树杀
+ *      - 有通道：调用后与 exit 事件竞速等 graceMs，仍存活 → 树杀
+ *
+ * 依赖（spawn / 等待器 / 日志）全部构造注入，win32 语义可在任意宿主上单测。
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { agentStopperRegistry } from './agent-stopper.js';
+/** 退出判定统一口径（CLAUDE.md 红线）：exitCode !== null || signalCode !== null。 */
+function isAlive(proc) {
+    return proc.exitCode === null && proc.signalCode === null;
+}
+/** 默认等待器：exit 事件与定时器竞速，谁先到算谁。 */
+async function defaultWaitForExit(proc, ms) {
+    if (!isAlive(proc))
+        return false;
+    return new Promise((resolve) => {
+        let settled = false;
+        const onExit = () => finish(false);
+        const finish = (alive) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            proc.removeListener('exit', onExit);
+            resolve(alive);
+        };
+        proc.on('exit', onExit);
+        const timer = setTimeout(() => finish(isAlive(proc)), ms);
+    });
+}
+export function createWin32Terminator(deps) {
+    const spawnFn = deps.spawn ?? nodeSpawn;
+    const stoppers = deps.stoppers ?? agentStopperRegistry;
+    const waitForExit = deps.waitForExit ?? defaultWaitForExit;
+    const log = deps.log;
+    /** 树杀：taskkill /PID <pid> /T /F —— posix 负 PID 组杀的等价物。 */
+    function killTree(pid) {
+        if (pid === undefined) {
+            log?.(`win32 树杀跳过：子进程没有 pid（spawn 未成功）`);
+            return;
+        }
+        try {
+            // fire-and-forget：不等 taskkill 自身返回，退出由 proc 的 exit 事件驱动
+            const killer = spawnFn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            killer?.on?.('error', () => {
+                // taskkill 拉起失败不致命：调用方仍可走 killOrphan / 陈旧锁自愈
+            });
+        }
+        catch (error) {
+            log?.(`win32 树杀失败：taskkill 拉起异常 ${String(error)}`);
+        }
+    }
+    return {
+        async stop(proc, opts) {
+            if (!isAlive(proc))
+                return { requested: false, via: 'already-exited' };
+            if (proc.pid === undefined) {
+                // 与 posix 同口径：拿不到 pid 就没有可请求的终止目标，不能谎报 requested
+                log?.('win32 停止跳过：子进程没有 pid（spawn 未成功），按已退出处理');
+                return { requested: false, via: 'already-exited' };
+            }
+            if (opts.immediate) {
+                killTree(proc.pid);
+                return { requested: true, via: 'taskkill' };
+            }
+            const agent = deps.agent;
+            const stopper = agent === undefined ? undefined : stoppers.get(agent);
+            if (!stopper) {
+                // 无通道是合法状态：显式记录后走树杀，不做无意义的优雅空转
+                log?.(`win32 优雅停止跳过：agent=${agent ?? '(unknown)'} 无协议停止通道，直接树杀`);
+                killTree(proc.pid);
+                return { requested: true, via: 'skipped-no-channel' };
+            }
+            try {
+                await stopper(proc);
+            }
+            catch (error) {
+                // 通道异常不能吞掉终止流程：记录后继续走树杀兜底
+                log?.(`win32 协议停止通道异常，转入树杀：${String(error)}`);
+            }
+            if (!isAlive(proc))
+                return { requested: true, via: 'cooperative' };
+            const stillAlive = await waitForExit(proc, deps.graceMs);
+            if (!stillAlive)
+                return { requested: true, via: 'cooperative' };
+            killTree(proc.pid);
+            return { requested: true, via: 'taskkill' };
+        },
+        cleanupOnExit(proc) {
+            // M0 真机验证项（§9.2 矩阵）：本方法在 process.on('exit') 里调用，而
+            // killTree 依赖 libuv uv_spawn 在 exit handler 内同步发起 taskkill——
+            // 大概率可用（uv_spawn 本身同步），但与 posix 路径（同步 process.kill）
+            // 可靠性不等价；失败表现为 win32 上 bridge 退出后 agent 变孤儿。
+            if (!isAlive(proc))
+                return;
+            killTree(proc.pid);
+        },
+    };
+}
+//# sourceMappingURL=terminator-win32.js.map

package/dist/platform/terminator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 平台终止器 seam 的接口层（design.md §3.2 / §3.3）。
+ *
+ * Windows 没有可拦截的跨进程 SIGTERM、负 PID 无效，因此把「进程组 + 信号」
+ * 换成「协议停止通道 + 进程树杀」。本文件只放接口与平台分发，实现见
+ * terminator-posix.ts / terminator-win32.ts。
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { AgentStopperRegistry } from './agent-stopper.js';
+import type { TerminateResult } from './types.js';
+export { AgentStopperRegistry, agentStopperRegistry } from './agent-stopper.js';
+export type { AgentStopper } from './agent-stopper.js';
+/**
+ * 进程终止器。
+ *
+ * `stop` 的 `immediate` 语义与现状 `process-stopper` 的 `stop({immediate})` 对齐。
+ * 设计文档声明返回 `Promise<void>`，这里收窄为 {@link TerminateResult}：降级
+ * 必须可观测（优雅段被跳过、走了树杀、进程早已退出），否则 win32 上「等一个
+ * 不会来的退出事件」这类退化无法被发现。
+ */
+export interface Terminator {
+    stop(proc: ChildProcess, opts: {
+        immediate: boolean;
+    }): Promise<TerminateResult>;
+    /** 进程级退出清理：fire-and-forget 强杀 */
+    cleanupOnExit(proc: ChildProcess): void;
+}
+export interface TerminatorDeps {
+    /** 优雅等待窗口（毫秒）；win32 为协议停止后的等待，posix 为 SIGTERM→SIGKILL 的 grace */
+    graceMs: number;
+    /** 平台注入（测试用）；默认当前宿主平台 */
+    platform?: NodeJS.Platform;
+    /** 当前 run 所属 agent（win32 查协议通道用；posix 忽略） */
+    agent?: string;
+    /** 协议通道注册表注入（测试隔离）；默认进程级单例 */
+    stoppers?: AgentStopperRegistry;
+    /** 日志注入（测试用）；默认走 logger 单例 */
+    log?: (level: 'debug' | 'info', message: string) => void;
+}
+/**
+ * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
+ * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
+ */
+export declare function createTerminator(deps: TerminatorDeps): Terminator;

package/dist/platform/terminator.js

@@ -0,0 +1,24 @@
+import { currentPlatform, isWin32 } from './select.js';
+import { createPosixTerminator } from './terminator-posix.js';
+import { createWin32Terminator } from './terminator-win32.js';
+// 注册表实现在 agent-stopper.ts（避免与 terminator-win32.ts 循环依赖），
+// 这里 re-export 以维持调用方的单一入口。
+export { AgentStopperRegistry, agentStopperRegistry } from './agent-stopper.js';
+/**
+ * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
+ * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
+ */
+export function createTerminator(deps) {
+    const platform = deps.platform ?? currentPlatform;
+    if (isWin32(platform)) {
+        return createWin32Terminator({
+            graceMs: deps.graceMs,
+            agent: deps.agent,
+            stoppers: deps.stoppers,
+            // win32 侧日志不带级别（无 debug 级输出），统一按 info 透传
+            log: deps.log ? (message) => deps.log?.('info', message) : undefined,
+        });
+    }
+    return createPosixTerminator({ graceMs: deps.graceMs, log: deps.log });
+}
+//# sourceMappingURL=terminator.js.map

package/dist/platform/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 平台 seam 纯类型。
+ */
+/**
+ * spawn 发现规格 —— resolveExecutable 的产出（v2 §4.3，仅探测/诊断用）。
+ * v2 收窄：.cmd 垫片命中即报告垫片路径本身，不再解析内容定位入口；
+ * 执行统一走 platform/spawn.ts 的 cross-spawn 包装。
+ */
+export interface LaunchSpec {
+    kind: 'direct';
+    /** 可执行文件路径（posix 绝对路径 / win32 含 .cmd 垫片路径） */
+    file: string;
+}
+/** 终止结果（§3.2 win32 状态机产出；可观测降级用）。 */
+export interface TerminateResult {
+    /** 进程是否已确认被请求终止（不代表已退出，退出由 exit 事件驱动） */
+    requested: boolean;
+    /**
+     * 终止途经：协议停止 / 强制终止 / 进程已退出 / 无通道跳过优雅段。
+     * 强制终止在 posix 下是 SIGKILL 组杀、win32 下是 taskkill 树杀，同枚举值。
+     */
+    via: 'cooperative' | 'taskkill' | 'already-exited' | 'skipped-no-channel';
+}

package/dist/platform/types.js

@@ -0,0 +1,5 @@
+/**
+ * 平台 seam 纯类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/restart.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawnProcess } from './platform/spawn.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getLogger } from './logger/index.js';
@@ -24,10 +24,12 @@ const POLL_MS = 100;
 export function spawnReplacementBridge(logsDir) {
     fs.mkdirSync(logsDir, { recursive: true });
     const out = fs.openSync(path.join(logsDir, 'restart-child.log'), 'a');
-    const child = spawn(process.execPath, process.argv.slice(1), {
+    const child = spawnProcess(process.execPath, process.argv.slice(1), {
         cwd: process.cwd(),
         env: { ...process.env, [RESTART_WAIT_PID_ENV]: String(process.pid) },
         detached: true,
+        // win32：detached 继任者默认会闪控制台窗口（§3.7）
+        windowsHide: true,
         stdio: ['ignore', out, out],
     });
     // Late spawn errors (e.g. binary removed mid-run) must not crash the

package/dist/router/card-helpers.d.ts

@@ -28,13 +28,40 @@ type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
  */
 export declare function sessionEventPanel(ev: AgentSessionContentEvent, index: number, totalEvents: number, tailExpandedCount?: number, agentKind?: string): object;
 export { markdownDiv };
+/** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
+export declare const PAGE_JUMP_INPUT_NAME = "pageInput";
+/** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
+export declare const PAGE_JUMP_INVALID_HINT = "\u8BF7\u8F93\u5165\u6709\u6548\u7684\u9875\u7801\uFF08\u6B63\u6574\u6570\uFF09";
 /**
- * Build a CardKit 2.0 pagination bar (prev-button / page-label / next-button
- * columns). Shared by /ls, /ws, /resume, /active, /order.
+ * 解析分页卡「跳转页码」输入框的提交值。
  *
- * Returns the `column_set` element (plus caller appends an `hr`). Each caller
- * supplies its own callback cmd + extra value fields and label text (semantic
- * differences are preserved, not silently unified).
+ * 三态返回：
+ * - `undefined` — 未输入（空串/非字符串），调用方应回退到 `offset`（上一页/下一页）
+ * - `null`      — 输入非法（非正整数），调用方应回错误 toast 且不刷新卡片
+ * - `number`    — 页码换算出的 offset（页码从 1 开始）
+ */
+export declare function parseJumpOffset(inputValue: unknown, pageSize: number): number | null | undefined;
+/**
+ * Build the CardKit 2.0 pagination block shared by /ls, /ws, /resume, /active,
+ * /order.
+ *
+ * 第一性原理（2026-09-10 窄屏重设计）：分页栏要同时承载「页码信息」和「翻页
+ * 控件」两类需求。旧布局把两者塞进同一行 `column_set`（文案 weighted 4 : 输入
+ * weighted 2），手机窄屏下 auto 按钮先占走固有宽度，剩余宽度按 4:2 切分后文案
+ * 列只有百来像素、输入框只有几十像素——文案折行、输入框窄到没法点。
+ * 拆成两行后每一类都有足够的横向空间：
+ *
+ *   1. 页码文案独占整行（顶层 `div`），窄屏不折行；
+ *   2. 控件行 `column_set` = [上一页 auto] [跳转页码 input weighted] [下一页 auto]，
+ *      input 吃掉 auto 按钮之外的剩余宽度（窄屏约百来像素，桌面端更宽）。
+ *
+ * Returns an array of body elements: `[page-label div, controls column_set]`；
+ * 调用方展开进 `body.elements`（+ 自己的 `hr`）。input 仍留在控件 column_set
+ * 内部，不用 form 容器（form 触发 300123 / 200621 整卡不可用）。CardKit 2.0
+ * input 自带 ✓ 提交图标，提交值经 raw `action.input_value` 回传，见 connector
+ * includeRawEvent + router/card-action-payload.ts。
+ *
+ * 每个调用方自带 callback cmd / extra value / 文案（语义差异保留，不强行统一）。
  *
  * @param opts.cmd       The pagination callback command (e.g. 'ls.page').
  * @param opts.offset    Current page offset.
@@ -53,7 +80,7 @@ export declare function paginationBar(opts: {
     label: string;
     prevText?: string;
     nextText?: string;
-}): object;
+}): object[];
 /**
  * Build a session-history resume card (shared by auto-restore, /resume <id>,
  * config-switch resume, and run-completion notification).

package/dist/router/card-helpers.js

@@ -63,13 +63,51 @@ function eventLabel(ev, agentKind) {
     }
 }
 export { markdownDiv };
+/** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
+export const PAGE_JUMP_INPUT_NAME = 'pageInput';
+/** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
+export const PAGE_JUMP_INVALID_HINT = '请输入有效的页码（正整数）';
 /**
- * Build a CardKit 2.0 pagination bar (prev-button / page-label / next-button
- * columns). Shared by /ls, /ws, /resume, /active, /order.
+ * 解析分页卡「跳转页码」输入框的提交值。
  *
- * Returns the `column_set` element (plus caller appends an `hr`). Each caller
- * supplies its own callback cmd + extra value fields and label text (semantic
- * differences are preserved, not silently unified).
+ * 三态返回：
+ * - `undefined` — 未输入（空串/非字符串），调用方应回退到 `offset`（上一页/下一页）
+ * - `null`      — 输入非法（非正整数），调用方应回错误 toast 且不刷新卡片
+ * - `number`    — 页码换算出的 offset（页码从 1 开始）
+ */
+export function parseJumpOffset(inputValue, pageSize) {
+    if (typeof inputValue !== 'string' || inputValue.trim() === '')
+        return undefined;
+    const raw = inputValue.trim();
+    if (!/^[0-9]+$/.test(raw))
+        return null;
+    const page = Number(raw);
+    if (!Number.isFinite(page) || page < 1)
+        return null;
+    const size = Number.isFinite(pageSize) && pageSize > 0 ? Math.trunc(pageSize) : 1;
+    return (page - 1) * size;
+}
+/**
+ * Build the CardKit 2.0 pagination block shared by /ls, /ws, /resume, /active,
+ * /order.
+ *
+ * 第一性原理（2026-09-10 窄屏重设计）：分页栏要同时承载「页码信息」和「翻页
+ * 控件」两类需求。旧布局把两者塞进同一行 `column_set`（文案 weighted 4 : 输入
+ * weighted 2），手机窄屏下 auto 按钮先占走固有宽度，剩余宽度按 4:2 切分后文案
+ * 列只有百来像素、输入框只有几十像素——文案折行、输入框窄到没法点。
+ * 拆成两行后每一类都有足够的横向空间：
+ *
+ *   1. 页码文案独占整行（顶层 `div`），窄屏不折行；
+ *   2. 控件行 `column_set` = [上一页 auto] [跳转页码 input weighted] [下一页 auto]，
+ *      input 吃掉 auto 按钮之外的剩余宽度（窄屏约百来像素，桌面端更宽）。
+ *
+ * Returns an array of body elements: `[page-label div, controls column_set]`；
+ * 调用方展开进 `body.elements`（+ 自己的 `hr`）。input 仍留在控件 column_set
+ * 内部，不用 form 容器（form 触发 300123 / 200621 整卡不可用）。CardKit 2.0
+ * input 自带 ✓ 提交图标，提交值经 raw `action.input_value` 回传，见 connector
+ * includeRawEvent + router/card-action-payload.ts。
+ *
+ * 每个调用方自带 callback cmd / extra value / 文案（语义差异保留，不强行统一）。
  *
  * @param opts.cmd       The pagination callback command (e.g. 'ls.page').
  * @param opts.offset    Current page offset.
@@ -84,9 +122,9 @@ export function paginationBar(opts) {
     const hasNext = opts.offset + opts.pageSize < opts.total;
     const prevText = opts.prevText ?? '⬅ 上一页';
     const nextText = opts.nextText ?? '下一页 ➡';
-    const pageColumns = [];
+    const controls = [];
     if (hasPrev) {
-        pageColumns.push({
+        controls.push({
             tag: 'column',
             width: 'auto',
             vertical_align: 'center',
@@ -106,15 +144,30 @@ export function paginationBar(opts) {
             ],
         });
     }
-    pageColumns.push({
+    // 跳转页码输入：占满 auto 按钮之外的剩余宽度（窄屏可点、桌面不局促）。
+    // 提交后值经 raw.action.input_value 回传，见 connector includeRawEvent +
+    // router/card-action-payload.ts。
+    controls.push({
         tag: 'column',
         width: 'weighted',
         weight: 1,
         vertical_align: 'center',
-        elements: [{ tag: 'div', text: { tag: 'lark_md', content: opts.label } }],
+        elements: [
+            {
+                tag: 'input',
+                name: PAGE_JUMP_INPUT_NAME,
+                placeholder: { tag: 'plain_text', content: '跳转页码' },
+                behaviors: [
+                    {
+                        type: 'callback',
+                        value: { cmd: opts.cmd, pageSize: opts.pageSize, ...opts.extra },
+                    },
+                ],
+            },
+        ],
     });
     if (hasNext) {
-        pageColumns.push({
+        controls.push({
             tag: 'column',
             width: 'auto',
             vertical_align: 'center',
@@ -134,7 +187,10 @@ export function paginationBar(opts) {
             ],
         });
     }
-    return { tag: 'column_set', columns: pageColumns };
+    return [
+        { tag: 'div', text: { tag: 'lark_md', content: opts.label } },
+        { tag: 'column_set', columns: controls },
+    ];
 }
 /**
  * Build a session-history resume card (shared by auto-restore, /resume <id>,

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

@@ -2,7 +2,7 @@
  * Shared config card rendering logic.
  *
  * Builds CardKit 2.0 elements for config fields (boolean toggle, select dropdown, input).
- * Used by all agent config builders and the shared tabs (idle, output, logging).
+ * Used by all agent config builders and the shared tabs (idle, logging).
  */
 import { type AppConfig } from '../../../config/index.js';
 import type { ConfigField } from '../types.js';

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

@@ -2,7 +2,7 @@
  * Shared config card rendering logic.
  *
  * Builds CardKit 2.0 elements for config fields (boolean toggle, select dropdown, input).
- * Used by all agent config builders and the shared tabs (idle, output, logging).
+ * Used by all agent config builders and the shared tabs (idle, logging).
  */
 import { getConfigValue } from '../../../config/index.js';
 /** Build CardKit 2.0 elements for a list of config fields. */

package/dist/router/config-diff.d.ts

@@ -0,0 +1,4 @@
+import type { AppConfig } from '../config/index.js';
+/** 对比原始 config 与 pendingConfig，返回变化的 key→string 映射 */
+export declare function diffConfig(original: AppConfig, pending: AppConfig): Record<string, string | undefined>;
+export declare function setNestedValue(target: AppConfig, key: string, value: unknown): void;

package/dist/router/config-diff.js

@@ -0,0 +1,70 @@
+/**
+ * Config diff / nested-value helpers extracted from CommandRouter
+ * (2026-09 round-2 simplification). Pure functions — no router state —
+ * previously inlined as methods (collectDiff recursed only into itself).
+ */
+import { mapAgentKey, walkNestedContainer, assertSafeKeyPart } from '../config/index.js';
+/** 对比原始 config 与 pendingConfig，返回变化的 key→string 映射 */
+export function diffConfig(original, pending) {
+    const updates = {};
+    collectDiff('', original, pending, updates);
+    return updates;
+}
+/** 递归收集差异 */
+function collectDiff(prefix, original, pending, result) {
+    if (original === pending)
+        return;
+    // 如果 pending 是对象（非 null）但 original 不是对象，
+    // 把 original 当作空对象递归进入 pending 内部，
+    // 避免把整个对象转成 "[object Object]" 字符串
+    if (typeof pending === 'object' &&
+        pending !== null &&
+        (typeof original !== 'object' || original === null)) {
+        const pendObj = pending;
+        for (const k of Object.keys(pendObj)) {
+            const newKey = prefix ? `${prefix}.${k}` : k;
+            collectDiff(newKey, undefined, pendObj[k], result);
+        }
+        return;
+    }
+    if (typeof original !== 'object' ||
+        typeof pending !== 'object' ||
+        original === null ||
+        pending === null) {
+        // 叶子节点，记录差异
+        const key = prefix || 'root';
+        // pending 为 undefined 表示键被删除，必须保留 undefined 语义，
+        // 不能 String(pending) 成 "undefined"
+        result[key] = pending === undefined ? undefined : String(pending);
+        return;
+    }
+    // 两者都是对象，递归比较
+    const origObj = original;
+    const pendObj = pending;
+    const allKeys = new Set([...Object.keys(origObj), ...Object.keys(pendObj)]);
+    for (const k of allKeys) {
+        const newKey = prefix ? `${prefix}.${k}` : k;
+        collectDiff(newKey, origObj[k], pendObj[k], result);
+    }
+}
+export function setNestedValue(target, key, value) {
+    // Path mapping 共用 config 模块的 mapAgentKey（G11 Inconsistency 修复）：
+    // pi.xxx/codex.xxx/opencode.xxx → agents.xxx，claude.xxx 保持顶层
+    const mappedKey = mapAgentKey(key);
+    const parts = mappedKey.split('.');
+    // 复用 config 模块的 walkNestedContainer（含 __proto__/prototype/constructor
+    // 守卫与中间段补 {}），router 只保留 value=undefined → delete 分支。
+    const container = walkNestedContainer(target, parts, true);
+    const lastPart = parts[parts.length - 1];
+    assertSafeKeyPart(lastPart);
+    if (value === undefined) {
+        // value=undefined 表示"删除键"（如清空 reasoningEffort），
+        // 不能写成 undefined 值——diffConfig 会把 undefined 转成字面量 "undefined"
+        // 写入 config.yaml 并透传给 codex（ReasoningEffort::Custom("undefined")）。
+        delete container[lastPart];
+    }
+    else {
+        container[lastPart] = value;
+    }
+}
+//# sourceMappingURL=config-diff.js.map