lark-remote 0.1.7 → 0.1.8

package/dist/runner/kimi/acp/translator.d.ts

@@ -81,6 +81,14 @@ export declare class KimiAcpTranslator {
      * Handle a server request (reverse RPC from the ACP server).
      */
     handleServerRequest(id: number | string, method: string, params: unknown): AcpTranslatorEvent[];
+    /**
+     * Kimi elicitation form：requestedSchema.properties 按顺序解析为 UserQuestion[]
+     * （type:array → 多选；oneOf/anyOf const → 选项 label；title → header??question）。
+     * 题面完整文本只在 form 级 message 里合并出现（逐字段 title 可能只是短 header），
+     * 因此 message 作为卡片概要行（view.intro）透传。
+     * form 会丢弃非声明选项值 → isOther=false（卡片隐藏自定义答案输入）。
+     */
+    private handleElicitationCreate;
     /**
      * Produce a turn_started event. Called by the runner when session/prompt
      * is sent (no wire notification for this — self-produced).
@@ -108,6 +116,12 @@ export declare class KimiAcpTranslator {
     private handleToolCallUpdate;
     private handleUsageUpdate;
     private handleRequestPermission;
+    /**
+     * request_permission 兜底桥（elicitation/create 失败或旧版 kimi）：
+     * 选项为 q{n}_opt_{i}（allow_once，label 直取 name）+ q{n}_skip（reject_once，
+     * 跳过语义）。单题单选、无 Other（kimi 桥丢弃非声明值）。
+     */
+    private handlePermissionQuestion;
     /**
      * Derive the approval decision list from the server's offered options.
      * accept/decline/cancel are universal; acceptForSession requires an

package/dist/runner/kimi/acp/translator.js

@@ -28,6 +28,7 @@
  *   turn_started (self-produced)   → operationKind 'turn'/'compaction'
  *   session/request_permission     → approval_requested
  */
+import { makeQuestionApprovalEvent } from '../../question-common.js';
 import { NotificationMethod, ServerRequestMethod, SessionEventType, } from '../../common/acp/protocol-types.js';
 import { getLogger } from '../../../logger/index.js';
 /**
@@ -96,8 +97,41 @@ export class KimiAcpTranslator {
         if (method === ServerRequestMethod.REQUEST_PERMISSION) {
             return this.handleRequestPermission(id, params);
         }
+        if (method === ServerRequestMethod.ELICITATION_CREATE) {
+            return this.handleElicitationCreate(id, params);
+        }
         return [];
     }
+    /**
+     * Kimi elicitation form：requestedSchema.properties 按顺序解析为 UserQuestion[]
+     * （type:array → 多选；oneOf/anyOf const → 选项 label；title → header??question）。
+     * 题面完整文本只在 form 级 message 里合并出现（逐字段 title 可能只是短 header），
+     * 因此 message 作为卡片概要行（view.intro）透传。
+     * form 会丢弃非声明选项值 → isOther=false（卡片隐藏自定义答案输入）。
+     */
+    handleElicitationCreate(requestId, params) {
+        const properties = params.requestedSchema?.properties ?? {};
+        const questions = [];
+        for (const [key, prop] of Object.entries(properties)) {
+            const q = elicitationPropertyToQuestion(prop);
+            if (!q) {
+                getLogger().warn(`[kimi-acp-translator] elicitation property skipped: key=${key}`);
+                continue;
+            }
+            questions.push(q);
+        }
+        if (questions.length === 0) {
+            // 无法解析 → 交还 runner 自动响应（不悬挂服务端）。
+            return [];
+        }
+        const message = params.message?.trim();
+        const single = questions.length === 1;
+        const intro = message && (!single || message !== questions[0].question) ? message : undefined;
+        const event = makeQuestionApprovalEvent(requestId, questions, params.sessionId);
+        if (intro)
+            event.view.intro = intro;
+        return [event];
+    }
     /**
      * Produce a turn_started event. Called by the runner when session/prompt
      * is sent (no wire notification for this — self-produced).
@@ -274,9 +308,20 @@ export class KimiAcpTranslator {
     // Private approval handlers
     // =========================================================================
     handleRequestPermission(requestId, params) {
-        // §5.4: Question elicitation auto-respond cancelled
-        if (params.isQuestion || !params.toolCall) {
-            getLogger().info(`[kimi-acp-translator] question elicitation detected, auto-responding cancelled (requestId=${requestId})`);
+        // §5.4 升级：question elicitation 识别（isQuestion 标记 / AskUserQuestion
+        // toolCall 标题 / q{n}_opt_* 选项命名空间）→ 渲染为提问卡；无法解析的
+        // 退化形态（无 toolCall 也无选项）仍返回 [] 由 runner 自动响应 cancelled。
+        const toolCall = params.toolCall;
+        const questionMarker = params.isQuestion === true ||
+            toolCall?.title === 'AskUserQuestion' ||
+            optionIdsMatchQuestionNamespace(params.options);
+        if (questionMarker) {
+            return this.handlePermissionQuestion(requestId, params);
+        }
+        // §5.4：无 toolCall 且无提问标记 → 无法构成审批视图，返回 [] 由 runner
+        // 自动响应 cancelled（服务端不会悬挂）。
+        if (!toolCall) {
+            getLogger().info(`[kimi-acp-translator] permission request without toolCall, auto-responding cancelled (requestId=${requestId})`);
             return [];
         }
         const view = {
@@ -301,6 +346,27 @@ export class KimiAcpTranslator {
             },
         ];
     }
+    /**
+     * request_permission 兜底桥（elicitation/create 失败或旧版 kimi）：
+     * 选项为 q{n}_opt_{i}（allow_once，label 直取 name）+ q{n}_skip（reject_once，
+     * 跳过语义）。单题单选、无 Other（kimi 桥丢弃非声明值）。
+     */
+    handlePermissionQuestion(requestId, params) {
+        const selectable = (params.options ?? []).filter((opt) => /^q\d+_opt_\d+$/.test(opt.optionId));
+        if (selectable.length === 0) {
+            getLogger().info(`[kimi-acp-translator] question elicitation unparseable, auto-responding cancelled (requestId=${requestId})`);
+            return [];
+        }
+        const questionText = extractQuestionText(params.toolCall);
+        const questions = [
+            {
+                question: questionText,
+                isOther: false,
+                options: selectable.map((opt) => ({ label: opt.name })),
+            },
+        ];
+        return [makeQuestionApprovalEvent(requestId, questions, params.sessionId)];
+    }
     /**
      * Derive the approval decision list from the server's offered options.
      * accept/decline/cancel are universal; acceptForSession requires an
@@ -333,4 +399,43 @@ export class KimiAcpTranslator {
 function truncate(text, maxLen) {
     return text.length <= maxLen ? text : text.slice(0, maxLen) + '…';
 }
+/** elicitation schema property → UserQuestion（无法解析返回 null）。 */
+function elicitationPropertyToQuestion(prop) {
+    const title = prop.title?.trim();
+    if (!title)
+        return null;
+    const multiSelect = prop.type === 'array';
+    const rawOptions = multiSelect ? prop.items?.anyOf : prop.oneOf;
+    const options = (rawOptions ?? [])
+        .filter((opt) => typeof opt?.const === 'string')
+        .map((opt) => ({
+        label: opt.const,
+        ...(opt.description ? { description: opt.description } : {}),
+    }));
+    if (options.length === 0)
+        return null;
+    return {
+        question: title,
+        header: title,
+        multiSelect,
+        isOther: false,
+        options,
+    };
+}
+/** 选项命名空间是否匹配 kimi question 桥（q{n}_opt_{i} / q{n}_skip）。 */
+function optionIdsMatchQuestionNamespace(options) {
+    return (options ?? []).some((opt) => /^q\d+_(opt_\d+|skip)$/.test(opt.optionId));
+}
+/** 从 AskUserQuestion toolCall 提取题面（content 文本优先，标题兜底）。 */
+function extractQuestionText(toolCall) {
+    const content = toolCall?.content;
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            const text = block.content?.text;
+            if (typeof text === 'string' && text.trim())
+                return text.trim();
+        }
+    }
+    return toolCall?.title?.trim() || '请选择';
+}
 //# sourceMappingURL=translator.js.map

package/dist/runner/pi/rpc/runner.d.ts

@@ -14,8 +14,7 @@
  * turn idle watchdog, connection-lost retry). Differences:
  *   - pi binds the session at spawn via `--session-id` (no RPC resume-by-id);
  *     the PiRpcConnectionManager respawns when the requested session changes.
- *   - no approval server-requests (pi RPC exposes none in this scope) →
- *     respondApproval is a no-op.
+ *   - pi，极简风格，没有 Ask User question。
  *   - `prompt` ack ≠ turn completion; the turn ends on `agent_settled`.
  */
 import type { AgentSessionReader, AgentEvent, AgentStatusInfo, SpawnOptions } from '../../types.js';
@@ -71,10 +70,5 @@ export declare class PiRpcRunner extends ConnectionBasedRunner<PiRpcClient, PiRp
      * completion (the completion signal); `compaction_*` events stream meanwhile.
      */
     runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
-    /**
-     * Approvals are out of scope for pi RPC (no server requests surface in this
-     * integration); the bridge's duck-typed respondApproval call is a no-op.
-     */
-    respondApproval(_requestId: number | string, _response: unknown): Promise<void>;
     private handleEvent;
 }

package/dist/runner/pi/rpc/runner.js

@@ -14,8 +14,7 @@
  * turn idle watchdog, connection-lost retry). Differences:
  *   - pi binds the session at spawn via `--session-id` (no RPC resume-by-id);
  *     the PiRpcConnectionManager respawns when the requested session changes.
- *   - no approval server-requests (pi RPC exposes none in this scope) →
- *     respondApproval is a no-op.
+ *   - pi，极简风格，没有 Ask User question。
  *   - `prompt` ack ≠ turn completion; the turn ends on `agent_settled`.
  */
 import { ConnectionBasedRunner } from '../../common/connection-based-runner.js';
@@ -172,16 +171,8 @@ export class PiRpcRunner extends ConnectionBasedRunner {
             this.pushEvents([translator.produceCompactResult(opts.sessionId, response)]);
         });
     }
-    /**
-     * Approvals are out of scope for pi RPC (no server requests surface in this
-     * integration); the bridge's duck-typed respondApproval call is a no-op.
-     */
-    async respondApproval(_requestId, _response) {
-        // no-op
-    }
     handleEvent(evt) {
-        const events = this.currentTranslator?.handleEvent(evt) ?? [];
-        this.pushEvents(events);
+        this.pushEvents(this.currentTranslator?.handleEvent(evt) ?? []);
     }
 }
 /** Build pi `--mode rpc` spawn args. `sessionId` is bound at spawn (pi has no

package/dist/runner/probe.js

@@ -28,6 +28,9 @@ const BINARY_MAP = {
     opencode: 'opencode',
     pi: 'pi',
     kimi: 'kimi',
+    // DSH is an HTTP-only agent (no CLI). `which ''` fails → reported unavailable,
+    // which is semantically correct for the /config availability display.
+    dsh: '',
 };
 const CACHE_TTL_MS = 5 * 60_000;
 /** Module-level cache, survives across calls within the process. */
@@ -65,7 +68,9 @@ export async function probeAgentAvailability(kind) {
  * on resource-constrained devices.
  */
 export async function probeAllAgents() {
-    const kinds = Object.keys(BINARY_MAP);
+    // Skip agents with no CLI binary (DSH is HTTP-only, binary === ''): the
+    // probe / availability display only covers spawn-able agents.
+    const kinds = Object.keys(BINARY_MAP).filter((k) => BINARY_MAP[k] !== '');
     const entries = await Promise.all(kinds.map(async (k) => [k, await probeAgentAvailability(k)]));
     return new Map(entries);
 }

package/dist/runner/question-common.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AskUserQuestion 公共工厂与映射（agent 无关）。
+ *
+ * 接入约定（types.ts UserQuestion 注释的落点）：
+ * - 各 runner 用 makeQuestionApprovalEvent 构造标准 question 审批事件，
+ *   避免四处手拼事件形状（claude/codex/kimi/pi 共用）；
+ * - 用户答案经 ApprovalCoordinator 以 {问题文本: 值} 回传 runner 后，
+ *   用 mapAnswersByIndex 按问题顺序展开，再做协议级编码
+ *   （Codex 问题 id、Kimi q{i}、Pi 单题取值）。
+ */
+import type { ApprovalRequestedEvent, UserQuestion } from './types.js';
+export interface QuestionEventOptions {
+    /** Per-request 审批超时覆盖（Codex autoResolutionMs）。 */
+    timeoutMs?: number;
+}
+/**
+ * 构造标准 question approval_requested 事件。
+ * availableDecisions 恒为空数组：提问只能作答或跳过（decline/cancel 是
+ * coordinator 的通用安全兜底），不允许 accept/decline 按钮混入提问卡。
+ */
+export declare function makeQuestionApprovalEvent(requestId: number | string, questions: UserQuestion[], threadId: string, opts?: QuestionEventOptions): ApprovalRequestedEvent;
+/**
+ * 按问题顺序把 coordinator 回传的 {问题文本: 值} 展开成索引对齐数组。
+ * 未作答的问题对应 undefined，由各 runner 决定协议编码（跳过/空 answers）。
+ */
+export declare function mapAnswersByIndex(questions: UserQuestion[], answers: Record<string, string | string[]>): Array<string | string[] | undefined>;

package/dist/runner/question-common.js

@@ -0,0 +1,42 @@
+/**
+ * AskUserQuestion 公共工厂与映射（agent 无关）。
+ *
+ * 接入约定（types.ts UserQuestion 注释的落点）：
+ * - 各 runner 用 makeQuestionApprovalEvent 构造标准 question 审批事件，
+ *   避免四处手拼事件形状（claude/codex/kimi/pi 共用）；
+ * - 用户答案经 ApprovalCoordinator 以 {问题文本: 值} 回传 runner 后，
+ *   用 mapAnswersByIndex 按问题顺序展开，再做协议级编码
+ *   （Codex 问题 id、Kimi q{i}、Pi 单题取值）。
+ */
+/**
+ * 构造标准 question approval_requested 事件。
+ * availableDecisions 恒为空数组：提问只能作答或跳过（decline/cancel 是
+ * coordinator 的通用安全兜底），不允许 accept/decline 按钮混入提问卡。
+ */
+export function makeQuestionApprovalEvent(requestId, questions, threadId, opts) {
+    const view = {
+        requestId,
+        kind: 'question',
+        questions,
+        availableDecisions: [],
+    };
+    return {
+        type: 'approval_requested',
+        requestId,
+        kind: 'question',
+        threadId,
+        turnId: '',
+        itemId: '',
+        view,
+        ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * 按问题顺序把 coordinator 回传的 {问题文本: 值} 展开成索引对齐数组。
+ * 未作答的问题对应 undefined，由各 runner 决定协议编码（跳过/空 answers）。
+ */
+export function mapAnswersByIndex(questions, answers) {
+    return questions.map((q) => answers[q.question]);
+}
+//# sourceMappingURL=question-common.js.map

package/dist/runner/types.d.ts

@@ -25,11 +25,18 @@ export interface ApprovalRequestedEvent {
     type: 'approval_requested';
     /** JSON-RPC id of the server request. Wire type is string | integer — keep raw. */
     requestId: number | string;
-    kind: 'command' | 'file' | 'permissions' | 'question';
+    kind: 'command' | 'file' | 'permissions' | 'question' | 'tool';
     threadId: string;
     turnId: string;
     itemId: string;
     view: ApprovalView;
+    /**
+     * Per-request 审批超时覆盖（毫秒）。由 runner 在翻译时填入
+     * （Codex autoResolutionMs），coordinator 优先使用；
+     * 缺省回落 run 级默认超时。放在事件上而非桥按 agentKind 分支，
+     * 保证公共层无 agent 分支。
+     */
+    timeoutMs?: number;
     timestamp?: string;
 }
 export interface ApprovalResolvedEvent {
@@ -67,22 +74,52 @@ export type ApprovalAction = {
 } | {
     action: 'cancel';
 }
-/** Claude AskUserQuestion 答案（question → label 或 label[]）。 */
+/**
+ * AskUserQuestion 答案（question → label 或 label[]）。
+ * notes：Codex user_note 补充说明（question → 文本），runner 编码为
+ * "user_note: <text>" 条目；其他 agent 忽略该字段。
+ */
  | {
     action: 'answer';
     answers: Record<string, string | string[]>;
+    notes?: Record<string, string>;
 };
-/** Claude Code AskUserQuestion 的单个选项（control_request input.questions[].options[]）。 */
-export interface ClaudeUserQuestionOption {
+/** AskUserQuestion 公共契约（Agent 无关）的单个选项。 */
+export interface UserQuestionOption {
     label: string;
     description?: string;
 }
-/** Claude Code AskUserQuestion 的单个问题（control_request input.questions[]）。 */
-export interface ClaudeUserQuestion {
+/**
+ * AskUserQuestion 公共契约（Agent 无关）的单个问题。
+ *
+ * 接入约定（新 agent 接入 AskUserQuestion 时在这里扩展，禁止在 coordinator /
+ * renderer / router 里写 agent 分支）：
+ * 1. 各 agent runner 把协议提问翻译为 `ApprovalView{ kind:'question', questions }`；
+ * 2. 用户回答经 ApprovalCoordinator 收集，以 `ApprovalAction{action:'answer',
+ *    answers:{问题文本: string|string[]}}` 回传 runner；
+ * 3. runner 侧把文本 key 答案翻译回自己协议的 shape（Claude 直接用文本 key；
+ *    Codex 需按问题 id 映射）。
+ */
+export interface UserQuestion {
+    /** Agent 侧问题唯一标识（Codex request_user_input 的 id 预留；Claude 无此字段）。 */
+    id?: string;
     question: string;
     header?: string;
     multiSelect?: boolean;
-    options: ClaudeUserQuestionOption[];
+    options: UserQuestionOption[];
+    /** 是否允许自定义答案（Codex isOther 预留；当前单选渲染层恒提供 Other 输入）。 */
+    isOther?: boolean;
+    /** 敏感输入（Codex isSecret 预留）。 */
+    isSecret?: boolean;
+    /** 自由文本题的输入框占位提示（渲染层自由文本题 input）。 */
+    placeholder?: string;
+    /**
+     * 是否渲染「补充说明（可选）」输入（Codex user_note；数据驱动无 agent 分支）。
+     * note 是选项之外的附加文本，随答案提交，不单独构成答案。
+     */
+    allowNote?: boolean;
+    /** 当前已填写的补充说明（卡片回显；coordinator answerNote 回流）。 */
+    note?: string;
     /**
      * 当前已选选项 label（卡片渲染与多选切换用；单选在协调器内即时提交）。
      * 与 permissions.items.selected 同模式：协调器原地更新后以
@@ -92,10 +129,24 @@ export interface ClaudeUserQuestion {
 }
 export interface ApprovalView {
     requestId: number | string;
-    kind: 'command' | 'file' | 'permissions' | 'question';
+    kind: 'command' | 'file' | 'permissions' | 'question' | 'tool';
     reason?: string;
+    /**
+     * 提问卡顶部概要行（数据驱动，无 agent 分支）：Kimi elicitation form 的
+     * 题面只在 form 级 message 里合并出现，逐字段 title 可能只是短 header，
+     * 概要行用于展示完整题干。
+     */
+    intro?: string;
     command?: string;
     commandCwd?: string;
+    /**
+     * 被审批的工具名（kind === 'tool' 时展示，如 ExitPlanMode）。非命令工具的
+     * 权限请求（plan 退出/通知型工具）input 无 command 语义，用工具名 + reason
+     * 表达审批内容，避免落入 command 槽位显示无意义 `{}`。
+     */
+    toolName?: string;
+    /** 原始 input 的 JSON 字符串（kind === 'tool' 且 input 非空时展示）。 */
+    toolInput?: string;
     fileChanges?: Array<{
         path: string;
         kind: 'add' | 'update' | 'delete';
@@ -115,7 +166,7 @@ export interface ApprovalView {
         }>;
     };
     /** Claude AskUserQuestion 问题列表（kind === 'question' 时存在）。 */
-    questions?: ClaudeUserQuestion[];
+    questions?: UserQuestion[];
     availableDecisions: string[];
     /** Raw payloads for structured decisions (e.g. acceptWithExecpolicyAmendment). */
     decisionPayloads?: Record<string, unknown>;
@@ -283,12 +334,14 @@ export interface Runner {
      */
     unregisterExitHandlers?(): void;
 }
-export type AgentKind = 'claude' | 'codex' | 'opencode' | 'pi' | 'kimi';
+export type AgentKind = 'claude' | 'codex' | 'opencode' | 'pi' | 'kimi' | 'dsh';
 /** Unified session descriptor returned by every AgentSessionReader. */
 export interface AgentSession {
     sessionId: string;
     summary: string;
     mtime: number;
+    /** DSH：session 创建时固定的 preset；其他 agent 无此概念（undefined）。 */
+    agentPreset?: string;
 }
 /** A single renderable event from session history. */
 export interface AgentSessionContentEvent {

package/dist/session/claude/sessions.js

@@ -154,7 +154,7 @@ function isSessionActive(filePath, mtimeMs, now = Date.now()) {
         // Explicit terminal markers — regardless of mtime. Claude CLI 2.x uses
         // `last-prompt` / `mode` (no `result` event) to mark turn end, so a
         // 24-minute-old session with a last-prompt tail is already done
-        // (regression 2026-06-21: c5e929a7 falsely reported as active).
+        // (regression 2026-06-21: previously falsely reported as active).
         const TERMINAL_TYPES = new Set(['result', 'last-prompt', 'mode', 'permission-mode']);
         if (typeof obj.type === 'string' && TERMINAL_TYPES.has(obj.type))
             return false;
@@ -224,7 +224,16 @@ export function isClaudeSessionActive(sessionId, cwd, opts = {}) {
  */
 function scalarScan(filePath) {
     const acc = new UsageAccumulator();
-    const seenMessageIds = new Set();
+    // Per-message-id best usage record (per-field max). A streaming assistant
+    // message spans multiple jsonl lines sharing the same message id; some
+    // backends (third-party gateways, e.g. DeepSeek) write all-zero usage on
+    // the early placeholder lines (empty thinking block) and the real usage
+    // only on the final line carrying stop_reason. First-occurrence-wins dedup
+    // would pin the zero record and discard the real one (regression
+    // 2026-08-19: auto-resume card per-run stats all 0). Per-field max
+    // reconstructs the full usage regardless of line order — on the official
+    // API every line repeats identical usage, so max is a no-op there.
+    const usageByMessageId = new Map();
     let lastPostTokens = 0;
     let tailOffset = -1;
     let lastAiTitle;
@@ -244,13 +253,13 @@ function scalarScan(filePath) {
             const usage = msg?.usage;
             if (usage) {
                 const msgId = msg?.id;
-                if (msgId && !seenMessageIds.has(msgId)) {
-                    seenMessageIds.add(msgId);
-                    acc.add({
-                        input: usage.input_tokens ?? 0,
-                        output: usage.output_tokens ?? 0,
-                        cacheRead: usage.cache_read_input_tokens ?? 0,
-                        cacheCreation: usage.cache_creation_input_tokens ?? 0,
+                if (msgId) {
+                    const prev = usageByMessageId.get(msgId);
+                    usageByMessageId.set(msgId, {
+                        input: Math.max(prev?.input ?? 0, usage.input_tokens ?? 0),
+                        output: Math.max(prev?.output ?? 0, usage.output_tokens ?? 0),
+                        cacheRead: Math.max(prev?.cacheRead ?? 0, usage.cache_read_input_tokens ?? 0),
+                        cacheCreation: Math.max(prev?.cacheCreation ?? 0, usage.cache_creation_input_tokens ?? 0),
                     });
                 }
             }
@@ -305,6 +314,12 @@ function scalarScan(filePath) {
             }
         }
     });
+    // Feed one best record per message id, in first-appearance order (Map
+    // preserves insertion order), so acc.last is the LAST message's full usage
+    // and totals sum each API response exactly once.
+    for (const record of usageByMessageId.values()) {
+        acc.add(record);
+    }
     // Build usage result (same logic as old aggregateSessionUsage)
     const t = acc.totals;
     const l = acc.last;
@@ -319,14 +334,19 @@ function scalarScan(filePath) {
     if (contextLength === 0 || lastWindow > contextLength) {
         contextLength = lastWindow;
     }
+    // 非累计字段 = 末轮（本 run）scope，累计字段 = session 总和（所有 run）。
+    // 对齐 codex reader 语义（§9.21：`last_token_usage`=单 turn 增量、
+    // `total_token_usage`=session 累计）——否则 jsonl 兜底路径会把 session 累计
+    // 当成"本 run"显示，与卡片"本 run ≤ 累计"不变量冲突（累计反而更小）。
+    const lastTotal = l ? l.input + l.output + l.cacheRead + l.cacheCreation : 0;
     const usage = {
-        inputTokens: t.input,
-        outputTokens: t.output,
+        inputTokens: l ? l.input : 0,
+        outputTokens: l ? l.output : 0,
         contextLength,
         compactCount: acc.compactCount,
-        cacheReadTokens: t.cacheRead > 0 ? t.cacheRead : undefined,
-        cacheCreationTokens: t.cacheCreation > 0 ? t.cacheCreation : undefined,
-        totalTokens: t.input + t.output + t.cacheRead + t.cacheCreation,
+        cacheReadTokens: l && l.cacheRead > 0 ? l.cacheRead : undefined,
+        cacheCreationTokens: l && l.cacheCreation > 0 ? l.cacheCreation : undefined,
+        totalTokens: lastTotal,
         cumulativeTotalTokens: t.input + t.output + t.cacheRead + t.cacheCreation,
         cumulativeInputTokens: t.input,
         cumulativeOutputTokens: t.output,
@@ -435,7 +455,9 @@ export function readSessionContent(sessionId, cwd, opts = {}) {
     // ~3×). Total parse count adds the index-miss fallback guard's fixed
     // early-stop overhead (~2 parses, independent of line count).
     const scan = scalarScan(filePath);
-    const usage = scan.usage.inputTokens + scan.usage.outputTokens > 0 ? scan.usage : undefined;
+    // 有 usage 即返回：非累计字段已是末轮 scope，命中判定用 session 累计兜底
+    // （末轮可能 input/output 为 0 而仍有 cacheRead，累计口径不会被末轮遮挡）。
+    const usage = (scan.usage.cumulativeTotalTokens ?? 0) > 0 ? scan.usage : undefined;
     // Extract events AFTER the last user message by re-reading + re-parsing
     // only the tail. If no user message was found (tailOffset === -1), fall
     // back to re-reading the whole file so the card still has something to

package/dist/session/dsh/index.d.ts

@@ -0,0 +1 @@
+export { DshSessionReader } from './sessions.js';

package/dist/session/dsh/index.js

@@ -0,0 +1,2 @@
+export { DshSessionReader } from './sessions.js';
+//# sourceMappingURL=index.js.map

package/dist/session/dsh/sessions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DshSessionReader — AgentSessionReader backed by the DSH Web Host over HTTP.
+ *
+ * The AgentSessionReader contract is fully synchronous (file-style readers),
+ * but DSH exposes only async HTTP. The reader therefore bridges with
+ * `spawnSync('curl', ...)` for its unary calls (session.list / session.history)
+ * — a synchronous HTTP round-trip to the local DSH host. This keeps the
+ * router/bridge interface contract intact without touching any upstream logic.
+ *
+ * listSessions: session.list → filter by cwd → sort by updatedAt desc → local
+ *   pagination (DSH v1 has no cursor pagination).
+ * readSessionContent: session.history → map SessionEvents to display events +
+ *   session-wide usage accumulation (assistant/message.usage).
+ */
+import type { AgentSession, AgentSessionReader, SessionContent } from '../../runner/index.js';
+interface DshSessionReaderOptions {
+    host?: string;
+    /** Injectable synchronous unary transport. Defaults to spawnSync curl. */
+    syncRequest?: (baseUrl: string, method: string, payload: unknown) => unknown;
+}
+export declare class DshSessionReader implements AgentSessionReader {
+    private readonly baseUrl;
+    private readonly syncRequest;
+    constructor(opts?: DshSessionReaderOptions);
+    private unary;
+    listSessions(cwd: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): {
+        sessions: AgentSession[];
+        total: number;
+    };
+    getNewestSession(cwd: string): AgentSession | null;
+    readSessionContent(sessionId: string, cwd: string, opts?: {
+        maxEvents?: number;
+    }): SessionContent;
+    isSessionActive(sessionId: string, cwd: string): boolean;
+}
+export {};