@v587d/capital-generation 2.9.0 → 2.9.2

package/CHANGELOG.md

@@ -7,6 +7,63 @@
 - **第三位（patch）**：不破坏既有工具 / 配置 / 会话的新增与修复（如 2.1.1、2.1.2）。
 - **第二位（minor）**：有需要用户知晓的行为变更，且段内附迁移说明（如 2.1.0 的图表呈现通道重做、2.2.0 的数据源与检索来源扩容、2.4.0 的**必须换宿主版本**、2.9.0 的选择器收敛与质检前置——本插件自己的工具与数据契约没变，所以只抬第二位）。
 
+## [2.9.2] - 2026-10-23
+
+`data_junior` 接入官方 PTC（`run_code`）：内层工具调用压进一段程序，多 Dataset 并发、`too_large`
+收窄与 skill 读取不再逐次往返模型。实机同类任务由 15 分钟级降到 2–3 分钟级；工具、数据契约、
+用户配置与宿主基线都不变。图表交付的收尾闸门同时修复结算通知竞争与同轮重复写入。
+
+### Added
+
+- **分析师的 PTC 执行面**：`data_junior` 只保留 `run_code` 直调，Dataset / skill / 出图委派 /
+  回传都通过 SDK `tools.*` 在程序内完成；不再挂 bash / pwsh，同时保住了“不读原始行”的边界。
+- **多 Dataset 并发与 `too_large` 自愈**：同一程序里可以 `Promise.all` 多份 `describe_dataset`；
+  结果过大时按 hint 收窄后继续，不再多开模型轮次。
+- **PTC 会话报告**：`npm run ptc:report` 汇总 `run_code` 段数、`Promise.all`、skill 打印、
+  `too_large` 与并发窗口，供实机验收。
+
+### Changed
+
+- **分析师提示词与三册协议同步 PTC 写法**：第一次加载协议就明确 skill 也要在 `run_code` 内用
+  `tools.skill`，不要直调原生工具；查询、profile 与可视化协议同步程序内调度。
+- **图表交付继续由收尾流写入**：`present_charts` 只记录清单，宿主在最终答复前统一落
+  `deliverables/presented`；结算通知不再阻塞收尾，且同一 exchange 不会重复写卡。
+
+### Fixed
+
+- **图表卡在结算通知竞争时丢失**：子 Agent 的 `subagent-settled` 通知在收尾流中途到达时，
+  不再被当成“还有待处理消息”；通知同时清掉已结算的直属子 Agent。
+- **同一轮重复交付**：后续 `finish` 帧缺少 `turn` 时不再写第二张卡。
+- **直调 skill 误调用**：软约束已把 `tools.skill` 提到第一次加载协议处；模型仍可能试错一次，
+  宿主拒绝后会自愈，不影响结果。
+
+## [2.9.1] - 2026-10-21
+
+修复实机 `dsh web` 反馈的两处收尾体验：图表交付不再散落在等待轮，最终答复不再只剩一句
+“分析已完成…见上”。不需要用户改配置，也没有宿主版本变化。
+
+### Added
+
+- **`present_charts` 收尾交付步骤**（仅主 Agent）：`render_chart` 出图后只回 `chart_ref`，主 Agent
+  在写最终答复前一次性登记本轮全部图表，卡片因此落在**最后一轮**答复末尾的「本轮文件改动 /
+  交付」行；refs 因上下文压缩丢失时可用 `task_id` 兜底。
+- **图表登记支持按 task 回查**：registry 记录标题，并可按 root session / 工作区 / task 列出；
+  fork / branch 出来的顶层会话仍能解析并登记自己子 Agent 出的图。
+
+### Changed
+
+- **自动模式不再在出图时自动登记交付**（单体载体保留）：旧行为会把卡片写进主 Agent 等待子 Agent
+  时所在的中间轮，DSH 折叠后用户容易错过。
+- **最终答复必须是自足总结**：禁止“分析已完成 / 结论见上 / 如上”一类指针式收尾；被结算通知
+  唤醒且无新信息时，要么不输出可见正文，要么重发一份自足总结。
+- 收口顺序写进人设与编排协议：委派全部结算 → 对账通过 → `present_charts` → 最终答复。
+
+### Fixed
+
+- fork / branch 顶层会话的 `parentSession` 是 seed 谱系，不再被当成委派链往上走（否则图表会
+  登记到被 fork 的旧会话，且 root 自己解析不到 `chart_ref`）。
+- 交付登记不再把内部记录字段 `owner_cwd` 混进模型可见回执。
+
 ## [2.9.0] - 2026-10-20
 
 新会话选择器收敛到三个用户模式：**自动模式 / 行情专家 / 资讯专员**。分析师与绘图专员继续注册，

package/README.md

@@ -18,8 +18,9 @@
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License"></a>
-  <a href="https://github.com/v587d/capital-generation/releases"><img src="https://img.shields.io/badge/version-2.9.0-9cf" alt="Version"></a>
+  <a href="https://github.com/v587d/capital-generation/releases"><img src="https://img.shields.io/badge/version-2.9.2-9cf" alt="Version"></a>
   <a href="https://www.npmjs.com/package/@v587d/capital-generation"><img src="https://img.shields.io/npm/v/%40v587d%2Fcapital-generation" alt="npm version"></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered-by-dsh"></a>
 </p>
 
 # Capital Generation
@@ -154,7 +155,7 @@ https://github.com/v587d/capital-generation
 
 - **查数据和资料：** 覆盖 A 股、港股、美股与期货等品种，由专用角色按需获取行情、财务、指数、基金、宏观行业与期货数据，检索公告、新闻和研报。共计 **128** 个数据收集能力和 **14** 个网页检索能力，部分公开数据源无需额外密钥；具体覆盖范围见 [数据收集能力表](docs/data-collector-capabilities.md) 和 [网页检索能力表](docs/web-retriever-capabilities.md)。
 - **数据质检：** 结构化数据不会直接进入模型上下文。每份数据先由分析师检查结构、时间轴、缺失与基础统计，再按受控方式汇总；原始数据行始终留在工具层。
-- **可视化：** 分析师判断数据适合图表，或你明确要图时，绘图专员会生成可交互图表；明确不要图时只完成质检。图表作为本轮交付物出现在会话里，可在侧栏查看或离线打开。了解处理流程可看 [Agent 角色说明](docs/agent-roles.md)。
+- **可视化：** 分析师判断数据适合图表，或你明确要图时，绘图专员会生成可交互图表；明确不要图时只完成质检。图表会登记为**最后一轮答复**的交付物，在答复末尾集中出现，可在侧栏查看或离线打开。了解处理流程可看 [Agent 角色说明](docs/agent-roles.md)。
 
 | 走势折线 | K 线与量价 |
 | :---: | :---: |
@@ -190,7 +191,7 @@ https://github.com/v587d/capital-generation
 - **安装后找不到模式？** 确认插件出现在「插件」→ 已安装列表；Web / CLI profile 安装后要重启该 profile，并在新会话选择模式。选择器里应看到自动模式、行情专家、资讯专员；分析师和绘图专员是自动模式的内部角色，不会出现在这里。
 - **配置在哪？** 打开「插件」→ 已安装的 **Capital Generation**，页面顶部就是「数据源 / 精选 Skills / 包含的组件」三格，五把密钥都在第一格；不在 DSH 的普通「设置」页面，也不用点进任何一行组件。保存密钥后新建会话再试。
 - **升级到 2.9.0 后，分析师和绘图专员去哪了？** 这一版把它们收进自动模式内部，不再出现在选择器与预设管理里，避免误开一个没有取数入口的空会话。旧会话仍能按原身份恢复；新任务直接用自动模式提出即可。
-- **桌面端升级后仍是旧版？** 桌面端安装时会固定所解析的版本，不会自动升级。卸载后重新安装，再到插件详情查看版本号；如需指定版本，可在地址末尾加 `#v2.9.0` 或 `@2.9.0`。
+- **桌面端升级后仍是旧版？** 桌面端安装时会固定所解析的版本，不会自动升级。卸载后重新安装，再到插件详情查看版本号；如需指定版本，可在地址末尾加 `#v2.9.2` 或 `@2.9.2`。
 - **刚发布的新版本装不到？** 桌面端取包时会跳过**刚发布不久**的版本（宿主侧包管理器的发布冷却策略，实测会静默装成上一个版本），国内镜像的同步也可能滞后一段时间。急着用最新代码，改用仓库地址安装最直接。
 - **网页抓取失败？** 配置卡片中的「允许启动本地提取网页内容」默认开启：AnySearch 提取失败时可尝试本机直连。关闭后，本机直连的具名来源查询也不可用；请检查该开关和网络连接。
 - **Wind 那部分会消耗积分？** 会。公告与新闻检索、宏观 / 行业 / 汇率指标、按日期区间取的历史 K 线都按次消耗你在 Wind 侧的额度；额度与条款以 Wind 为准，插件不做用量封顶。没配 `WIND_API_KEY` 时这几类不可用，其余功能照常。

package/chart-ui/README.md

@@ -90,9 +90,10 @@ route owner 自己负责，平台自己的 `/api` 与首页分别走 `connection
 
 ## 本轮呈现（官方交付通道）
 
-出图成功后，**宿主**（`@v587d/capital-generation` 的 `render_chart`）会往"用户正在看的根会话"
-追加一条**官方** `deliverables/presented` 事件，把 `capital-analysis/charts/<chart_id>/chart.html`
-登记为**本轮交付物**：
+auto 模式下 `render_chart` 不再自动登记：`present_charts` 只记录本轮图表，宿主在**收尾流结束、
+收尾消息落盘之前**写一条**官方** `deliverables/presented` 事件到"用户正在看的根会话"，把
+`capital-analysis/charts/<chart_id>/chart.html` 登记为**收尾轮交付物**（单体载体仍在出图时
+自动登记）：
 
 - 载荷只有官方契约字段：`turn` / `callId`（`capital-chart:<chart_id>` 句柄）/ `files[]`
   （工作区相对 `html_path` + 标题）——绝不含 rows、series、HTML 或绝对路径；

package/chart-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/capital-charts",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "自动模式的图表前端组件（浏览器半边 + 序列旁路路由）：由 @v587d/capital-generation 随包携带并作为 host 平面行挂载。",
   "license": "MIT",
   "type": "module",

package/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/config",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "自动模式的取数凭据与偏好配置行：卡片坐在 @v587d/capital-generation 插件主页的「配置」段，点这一行本身没有表单。",
   "license": "MIT",
   "type": "module",

package/lib/agents/bash-guard.d.ts

@@ -1,13 +1,17 @@
-/** Shell guard for bash/pwsh: blocks only doomed sandbox escalation; command content is never
- * inspected (the sandbox blocks writes, not reads/network). Delegated approvals are fixed to
- * `never`, so escalation auto-rejects with a misleading "user rejected"; block early instead.
- * Root escalation still uses ask; do not pin delegated sessions read-only (`store.writeContext`
- * needs workspace-write). `tools.guard` is monotonic; pre-execute is a rewritable waterfall. */
+/** Execution guard for bash/pwsh/run_code: blocks only doomed sandbox escalation; command/program
+ * content is never inspected (the sandbox blocks writes, not reads/network). Delegated approvals
+ * are fixed to `never`, so escalation auto-rejects with a misleading "user rejected"; block early
+ * instead. Root escalation still uses ask; do not pin delegated sessions read-only
+ * (`store.writeContext` needs workspace-write). `tools.guard` is monotonic; pre-execute is a
+ * rewritable waterfall. */
 import { type GuardedExecution, type PolicyContext } from './root-tool-policy.js';
+/** Both shell names on every platform plus the PTC transport: the preset mounts one shell pair for
+ * the root and `run_code` for data_junior, so matching only the local platform kills the Windows gate. */
+export declare const EXECUTION_ESCALATION_TOOL_NAMES: readonly ["bash", "pwsh", "run_code"];
 export type BashGuardExecution = GuardedExecution;
 /** States that the rejection is the system's, not the user's, and gives the recovery path. */
 export declare const SHELL_ESCALATION_UNREACHABLE: string;
-/** Reads identity plus `sandbox_permissions`/`justification`, never `command`; unknown identity fails closed. */
+/** Reads identity plus `sandbox_permissions`/`justification`, never `command`/`code`; unknown identity fails closed. */
 export declare function bashGuardReason(exec: BashGuardExecution | undefined): string | undefined;
 /** Installs on every Capital preset agent. Must listen on `ctx.root`: agent/created routes by
  * the agent object, so tagged standing-scope listeners never fire. Failures only warn. */

package/lib/agents/bash-guard.js

@@ -1,23 +1,26 @@
-/** Shell guard for bash/pwsh: blocks only doomed sandbox escalation; command content is never
- * inspected (the sandbox blocks writes, not reads/network). Delegated approvals are fixed to
- * `never`, so escalation auto-rejects with a misleading "user rejected"; block early instead.
- * Root escalation still uses ask; do not pin delegated sessions read-only (`store.writeContext`
- * needs workspace-write). `tools.guard` is monotonic; pre-execute is a rewritable waterfall. */
+/** Execution guard for bash/pwsh/run_code: blocks only doomed sandbox escalation; command/program
+ * content is never inspected (the sandbox blocks writes, not reads/network). Delegated approvals
+ * are fixed to `never`, so escalation auto-rejects with a misleading "user rejected"; block early
+ * instead. Root escalation still uses ask; do not pin delegated sessions read-only
+ * (`store.writeContext` needs workspace-write). `tools.guard` is monotonic; pre-execute is a
+ * rewritable waterfall. */
 import { agentSessionId, isCapitalPresetAgent, SHELL_TOOL_NAMES } from './root-tool-policy.js';
-/** Both names on every platform: the preset mounts a pair, so matching only the local platform kills the Windows gate. */
-const shellToolNames = new Set(SHELL_TOOL_NAMES);
+/** Both shell names on every platform plus the PTC transport: the preset mounts one shell pair for
+ * the root and `run_code` for data_junior, so matching only the local platform kills the Windows gate. */
+export const EXECUTION_ESCALATION_TOOL_NAMES = [...SHELL_TOOL_NAMES, 'run_code'];
+const executionToolNames = new Set(EXECUTION_ESCALATION_TOOL_NAMES);
 /** One listener set per root context: host policy and legacy call sites install once. */
 const installedRoots = new WeakSet();
 /** States that the rejection is the system's, not the user's, and gives the recovery path. */
-export const SHELL_ESCALATION_UNREACHABLE = 'shell 工具（bash / pwsh）的沙箱升级只有主 Agent 的会话能拿到用户审批：被委派的子会话拿不到'
+export const SHELL_ESCALATION_UNREACHABLE = '执行工具（bash / pwsh / run_code）的沙箱升级只有主 Agent 的会话能拿到用户审批：被委派的子会话拿不到'
     + '（框架把委派会话的审批策略固定为 never，不会去问用户），当前调用方也不是可确认的主 Agent 会话。'
     + '不要重试升级：缺数值用 describe_dataset / query_dataset，缺数据用 send_message 发 data_gap 回主 Agent。';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** Reads identity plus `sandbox_permissions`/`justification`, never `command`; unknown identity fails closed. */
+/** Reads identity plus `sandbox_permissions`/`justification`, never `command`/`code`; unknown identity fails closed. */
 export function bashGuardReason(exec) {
-    if (exec === undefined || typeof exec.name !== 'string' || !shellToolNames.has(exec.name))
+    if (exec === undefined || typeof exec.name !== 'string' || !executionToolNames.has(exec.name))
         return undefined;
     const args = isRecord(exec.arguments) ? exec.arguments : undefined;
     const escalated = args !== undefined && (args.sandbox_permissions !== undefined || args.justification !== undefined);
@@ -64,7 +67,7 @@ export function registerBashGuard(ctx) {
                     return;
                 const dispose = installAgentGuard(agent);
                 if (dispose === undefined) {
-                    ctx.logger?.warn('capital-generation: shell 闸门未生效（agent scope 上没有 tools.guard）：沙箱升级拦截只剩 persona 软约束');
+                    ctx.logger?.warn('capital-generation: 执行工具闸门未生效（agent scope 上没有 tools.guard）：沙箱升级拦截只剩 persona 软约束');
                     return;
                 }
                 const id = agentSessionId(agent);
@@ -72,7 +75,7 @@ export function registerBashGuard(ctx) {
                     guards.set(id, dispose);
             }
             catch (error) {
-                ctx.logger?.warn(`capital-generation: bash 闸门安装异常：${error instanceof Error ? error.message : String(error)}`);
+                ctx.logger?.warn(`capital-generation: 执行工具闸门安装异常：${error instanceof Error ? error.message : String(error)}`);
             }
         });
         const stopDisposed = listenCtx.on?.('agent/disposed', (payload) => {

package/lib/agents/root-tool-policy.js

@@ -47,6 +47,8 @@ export const ROOT_AGENT_DENIED_TOOLS = [
     'write',
     'edit',
 ];
+// ⛔ `run_code` belongs nowhere in this list: it is a reserved PTC transport name, so `restrict()`
+// throws on it. The root stays native; deployment-level `dsh-tools.mode` must not be set to ptc.
 export const CAPITAL_PRESET_ID = ROOT_PRESET_ID;
 export function isRootAgent(agent) {
     if (agent?.session === undefined)

package/lib/chart/artifact-ref.d.ts

@@ -1,5 +1,8 @@
 import type { SessionLike } from '../data-collector/store.js';
-/** One-hop scope: a token lets a nested child reuse its owner's scope. */
+/**
+ * Subagent children carry `origin: 'subagent'`; a user fork/branch root also has `parentSession`
+ * (seed lineage) and must stay its own scope. One hop: the token lets a nested child reuse its owner.
+ */
 export declare function chartSessionScopeId(session: SessionLike): string;
 export interface ChartArtifactRef {
     chart_ref: string;
@@ -10,6 +13,7 @@ export interface ChartArtifactRef {
     captured_at: number | null;
     kind: string;
     axis: 'time' | 'index';
+    title: string;
     chart_url: string | null;
     spec_path: string;
     series_path: string;
@@ -42,6 +46,7 @@ export declare class ChartArtifactRegistry {
         captured_at?: number | null;
         kind: string;
         axis: 'time' | 'index';
+        title: string;
         chart_url: string | null;
         spec_path: string;
         series_path: string;
@@ -55,6 +60,11 @@ export declare class ChartArtifactRegistry {
         task_id?: string | null;
     }): ChartArtifactRef;
     revoke(chartRef: string): boolean;
+    /** Charts of one session scope, for the model's final-turn delivery step; newest last. */
+    list(input: {
+        session: SessionLike;
+        task_id?: string | null;
+    }): ChartArtifactRef[];
     size(): number;
     private publicRecord;
 }

package/lib/chart/artifact-ref.js

@@ -8,9 +8,12 @@ function defaultChartRef() {
         : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
     return `chart_${suffix}`;
 }
-/** One-hop scope: a token lets a nested child reuse its owner's scope. */
+/**
+ * Subagent children carry `origin: 'subagent'`; a user fork/branch root also has `parentSession`
+ * (seed lineage) and must stay its own scope. One hop: the token lets a nested child reuse its owner.
+ */
 export function chartSessionScopeId(session) {
-    const parent = session.header?.parentSession;
+    const parent = session.header?.origin === 'subagent' ? session.header.parentSession : undefined;
     return typeof parent === 'string' && parent.length > 0 ? parent : session.id;
 }
 /**
@@ -56,6 +59,7 @@ export class ChartArtifactRegistry {
             captured_at: input.captured_at ?? null,
             kind: input.kind,
             axis: input.axis,
+            title: input.title,
             chart_url: input.chart_url,
             spec_path: input.spec_path,
             series_path: input.series_path,
@@ -91,12 +95,30 @@ export class ChartArtifactRegistry {
     revoke(chartRef) {
         return this.records.delete(chartRef);
     }
+    /** Charts of one session scope, for the model's final-turn delivery step; newest last. */
+    list(input) {
+        const now = this.now();
+        this.purgeExpired(now);
+        const scope = chartSessionScopeId(input.session);
+        const cwd = input.session.header?.cwd ?? null;
+        const records = [];
+        for (const record of this.records.values()) {
+            if (record.owner_scope_id !== scope || record.owner_cwd !== cwd)
+                continue;
+            if (input.task_id !== undefined && input.task_id !== null && record.task_id !== input.task_id)
+                continue;
+            records.push(record);
+        }
+        return records
+            .sort((left, right) => left.created_at - right.created_at)
+            .map((record) => this.publicRecord(record));
+    }
     size() {
         this.purgeExpired(this.now());
         return this.records.size;
     }
     publicRecord(record) {
-        const { owner_scope_id: _ownerScope, ...publicRecord } = record;
+        const { owner_scope_id: _ownerScope, owner_cwd: _ownerCwd, ...publicRecord } = record;
         return publicRecord;
     }
 }

package/lib/chart/delivery.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Chart delivery at the closing answer.
+ *
+ * DSH's deliverable card only replays `deliverables/presented` events whose seq is before the
+ * turn's closing assistant message, and a turn is final only after the fact. The one place that is
+ * provably before the closing message is the assistant stream's terminal `finish` chunk: the loop
+ * appends the message after the stream ends. So delivery is deferred to that chunk, gated on the
+ * root session being idle (no actionable inbox input, no running direct children), which is exactly
+ * the shape of a closing turn. Waiting/aborted/tool-call responses never flush.
+ *
+ * `subagent-settled` notices are not actionable input: they can arrive while the closing answer is
+ * already streaming. Counting them as pending would strand a card that the model has just selected,
+ * because the follow-up step often has nothing new to say.
+ */
+import type { ChartArtifactRegistry } from './artifact-ref.js';
+import type { ChartTurnEventInput } from './events.js';
+import type { SessionLike } from '../data-collector/store.js';
+/** Structural subset of `@deepseek-ai/dsh-llm` AssistantStreamFrame. */
+export interface AssistantStreamFrameLike {
+    readonly type?: string;
+    readonly attemptId?: string;
+    readonly turn?: number;
+    readonly chunk?: {
+        readonly type?: string;
+        readonly reason?: {
+            readonly kind?: string;
+        };
+        readonly blockType?: string;
+        readonly block?: {
+            readonly type?: string;
+        };
+    };
+}
+interface InboxStateLike {
+    'next-turn'?: readonly unknown[];
+    'next-step'?: readonly unknown[];
+}
+export interface ChartDeliveryOptions {
+    artifacts: ChartArtifactRegistry;
+    /** Writes one first-party deliverables/presented batch; must be synchronous (pre-message seq). */
+    publish: (sessionId: string, inputs: ChartTurnEventInput[]) => boolean;
+    /** Durable pending input; synchronous projection read. Absent means "cannot tell" → proceed. */
+    inboxOf?: (session: SessionLike) => InboxStateLike | undefined;
+    /** Bounded batch; the card collapses past four files and expands on demand. */
+    maxCharts?: number;
+}
+export interface ChartDelivery {
+    /** `present_charts` selection; merged across calls because models often retry in batches. */
+    request(session: SessionLike, inputs: ChartTurnEventInput[]): void;
+    acceptStream(session: SessionLike | undefined, frame: AssistantStreamFrameLike): void;
+    /** A new human message starts a new exchange: old charts must not ride into it. */
+    acceptUserMessage(sessionId: string, time: number): void;
+    acceptSubagentStart(info: {
+        id?: string;
+    }): void;
+    acceptSubagentEnd(info: {
+        id?: string;
+    }): void;
+    /** False until any stream frame was observed: callers fall back to immediate delivery. */
+    streaming(): boolean;
+    /** Diagnostics/tests: explicitly selected inputs for the current exchange. */
+    pending(sessionId?: string): number;
+}
+export declare const DEFAULT_MAX_DELIVERED_CHARTS = 32;
+export declare function createChartDelivery(options: ChartDeliveryOptions): ChartDelivery;
+export {};

package/lib/chart/delivery.js

@@ -0,0 +1,148 @@
+/** Settlement notices race the closing answer; they do not require another model step before the card. */
+function isSettledNotice(value) {
+    return value !== null && typeof value === 'object'
+        && value.source?.kind === 'subagent-settled';
+}
+function inboxMessages(inbox) {
+    return [...(inbox?.['next-turn'] ?? []), ...(inbox?.['next-step'] ?? [])];
+}
+export const DEFAULT_MAX_DELIVERED_CHARTS = 32;
+export function createChartDelivery(options) {
+    const maxCharts = options.maxCharts ?? DEFAULT_MAX_DELIVERED_CHARTS;
+    /** Plugin instances are per root agent, so one session id guards against child streams leaking in. */
+    let sessionId;
+    let explicit = [];
+    const exchangeStarts = new Map();
+    const fallbackStart = Date.now();
+    let lastFlushedTurn;
+    let sawFrame = false;
+    const attempts = new Map();
+    const running = new Map();
+    const owns = (session) => {
+        if (session?.id === undefined)
+            return false;
+        // A leaked child frame must not bind the manager: the card belongs to the user-facing root.
+        if (session.header?.origin === 'subagent')
+            return false;
+        sessionId ??= session.id;
+        return session.id === sessionId;
+    };
+    const autoInputs = (session) => options.artifacts
+        .list({ session })
+        .filter((artifact) => artifact.created_at >= (exchangeStarts.get(session.id) ?? fallbackStart))
+        .map((artifact) => ({
+        ownerSessionId: session.id,
+        chart_id: artifact.chart_id,
+        title: artifact.title,
+        html_path: artifact.html_path,
+    }));
+    /** A settled notice proves the child is done even if the lifecycle edge was missed or the parent
+     * observed it outside its scope. Reconciliating here keeps the stream-time gate synchronous. */
+    const reconcileSettled = (inbox) => {
+        for (const message of inboxMessages(inbox)) {
+            if (!isSettledNotice(message))
+                continue;
+            const childId = message.source?.senderSessionId;
+            if (typeof childId === 'string')
+                running.delete(childId);
+        }
+    };
+    const idle = (inbox) => {
+        if (running.size > 0)
+            return false;
+        if (inbox === undefined)
+            return true;
+        return inboxMessages(inbox).every(isSettledNotice);
+    };
+    const flush = (session, turn) => {
+        // A later step in the same exchange may omit `turn`; it still must not write a second card.
+        if (lastFlushedTurn !== undefined && (turn === undefined || lastFlushedTurn === turn))
+            return;
+        const inbox = options.inboxOf?.(session);
+        reconcileSettled(inbox);
+        if (!idle(inbox))
+            return;
+        const inputs = (explicit.length > 0 ? explicit : autoInputs(session)).slice(0, maxCharts);
+        if (inputs.length === 0)
+            return;
+        let written = false;
+        try {
+            written = options.publish(session.id, inputs);
+        }
+        catch {
+            written = false;
+        }
+        // Sentinel keeps a second turn-less finish in the same exchange from duplicating the card.
+        if (written)
+            lastFlushedTurn = turn ?? -1;
+    };
+    return {
+        request(session, inputs) {
+            if (!owns(session) || inputs.length === 0)
+                return;
+            const seen = new Set(explicit.map((item) => item.chart_id));
+            for (const input of inputs) {
+                if (seen.has(input.chart_id))
+                    continue;
+                seen.add(input.chart_id);
+                explicit.push(input);
+            }
+            if (explicit.length > maxCharts)
+                explicit = explicit.slice(0, maxCharts);
+        },
+        acceptStream(session, frame) {
+            if (!owns(session) || frame === undefined)
+                return;
+            sawFrame = true;
+            const attemptId = frame.attemptId ?? '__default__';
+            if (frame.type === 'start') {
+                attempts.set(attemptId, { toolCall: false });
+                return;
+            }
+            if (frame.type === 'end') {
+                attempts.delete(attemptId);
+                return;
+            }
+            const chunk = frame.chunk;
+            if (frame.type !== 'chunk' || chunk === undefined)
+                return;
+            const attempt = attempts.get(attemptId) ?? { toolCall: false };
+            attempts.set(attemptId, attempt);
+            if (chunk.type === 'tool-call-delta'
+                || (chunk.type === 'block-start' && chunk.blockType === 'tool-call')
+                || (chunk.type === 'block-end' && chunk.block?.type === 'tool-call')) {
+                attempt.toolCall = true;
+                return;
+            }
+            if (chunk.type !== 'finish' || chunk.reason?.kind !== 'stop' || attempt.toolCall)
+                return;
+            flush(session, frame.turn);
+        },
+        acceptUserMessage(id, time) {
+            exchangeStarts.set(id, time);
+            if (id !== sessionId)
+                return;
+            explicit = [];
+            lastFlushedTurn = undefined;
+        },
+        acceptSubagentStart(info) {
+            if (typeof info?.id !== 'string' || info.id.length === 0)
+                return;
+            running.set(info.id, 1);
+        },
+        acceptSubagentEnd(info) {
+            if (typeof info?.id !== 'string')
+                return;
+            // One child session runs one activation at a time; deleting also clears duplicate starts.
+            running.delete(info.id);
+        },
+        streaming() {
+            return sawFrame;
+        },
+        pending(id) {
+            if (id !== undefined && id !== sessionId)
+                return 0;
+            return explicit.length;
+        },
+    };
+}

package/lib/chart/events.d.ts

@@ -38,6 +38,8 @@ export interface ChartTurnEventInput {
 }
 export interface ChartEventPublisher {
     publish(input: ChartTurnEventInput): boolean;
+    /** One first-party event carrying every file; the turn cap counts events, not files. */
+    publishMany(ownerSessionId: string, inputs: ChartTurnEventInput[]): boolean;
     /** Diagnostics: queued charts not yet written. */
     pendingCount?(ownerSessionId?: string): number;
     /** Diagnostics: last publish trace, surfaced in receipts / disk so failures are visible without a terminal. */

package/lib/chart/events.js

@@ -33,7 +33,10 @@ function isAppendableSession(value) {
         && typeof value.append === 'function'
         && typeof value.id === 'string';
 }
+/** `parentSession` alone is seed lineage (a user fork); only `origin: 'subagent'` is delegation. */
 function parentSessionOf(session) {
+    if (session.header?.origin !== 'subagent')
+        return undefined;
     const parent = session.header?.parentSession;
     return typeof parent === 'string' && parent.length > 0 ? parent : undefined;
 }
@@ -157,7 +160,7 @@ function buildChartEventPublisher(ctx) {
         const key = `${owner.id}:${turn}`;
         const used = perTurn.get(key) ?? 0;
         if (used >= MAX_CHARTS_PER_TURN) {
-            warn(`图表对话流事件跳过：turn ${turn} 已达到 ${MAX_CHARTS_PER_TURN} 张上限`);
+            warn(`图表对话流事件跳过：turn ${turn} 已达到 ${MAX_CHARTS_PER_TURN} 次上限`);
             return false;
         }
         try {
@@ -171,6 +174,31 @@ function buildChartEventPublisher(ctx) {
         note(`图表已登记为本轮交付（owner=${owner.id}，turn=${turn}，${input.chart_id}）`);
         return true;
     };
+    const appendMany = (owner, turn, inputs) => {
+        if (inputs.length === 0)
+            return false;
+        const key = `${owner.id}:${turn}`;
+        const used = perTurn.get(key) ?? 0;
+        if (used >= MAX_CHARTS_PER_TURN) {
+            warn(`图表对话流事件跳过：turn ${turn} 已达到 ${MAX_CHARTS_PER_TURN} 次上限`);
+            return false;
+        }
+        const first = inputs[0];
+        if (first === undefined)
+            return false;
+        const payload = buildChartEventPayload(first, turn);
+        payload.files = inputs.map((item) => ({ path: item.html_path, description: item.title }));
+        try {
+            owner.append(CHART_DELIVERABLE_EVENT, payload);
+        }
+        catch (error) {
+            warn(`图表对话流事件写入失败（图表已落盘）：${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        perTurn.set(key, used + 1);
+        note(`图表已登记为本轮交付（owner=${owner.id}，turn=${turn}，${inputs.length} 张）`);
+        return true;
+    };
     /** Flush queued charts into a turn; the preferred hook is turn-stopping. */
     const flush = (ownerSessionId, turn) => {
         const queued = pending.get(ownerSessionId);
@@ -305,6 +333,32 @@ function buildChartEventPublisher(ctx) {
             lastPublishTrace = `${trace.join(' ')} 回合打开(turn=${lastTurn}) → ${written ? '已直接登记' : '写入失败'}`;
             return written;
         },
+        publishMany(ownerSessionId, inputs) {
+            const owner = resolveOwnerSession(sessions, ownerSessionId);
+            if (owner === undefined) {
+                lastPublishTrace = `owner 未解析：批量交付缺少可用 owner 会话`;
+                warn('图表对话流事件跳过：找不到批量交付的 owner 会话（图表已落盘，走 html_path 降级）');
+                return false;
+            }
+            const boundary = boundaryOf(owner);
+            const turn = boundary?.lastTurn;
+            if (typeof boundary?.openTurnStartSeq !== 'number' || typeof turn !== 'number' || !Number.isSafeInteger(turn) || turn < 1) {
+                // Between turns: queue each input so the existing flush path still delivers them later.
+                const queued = pending.get(owner.id) ?? [];
+                if (queued.length + inputs.length > MAX_PENDING_CHARTS) {
+                    lastPublishTrace = `owner=${owner.id} 批量寄存超限（${queued.length}+${inputs.length} > ${MAX_PENDING_CHARTS}）→ 未写入`;
+                    warn('图表对话流事件跳过：进程内寄存已超出上限（冲刷链路异常）');
+                    return false;
+                }
+                queued.push(...inputs);
+                pending.set(owner.id, queued);
+                lastPublishTrace = `owner=${owner.id} 回合未打开 → 已寄存 ${inputs.length} 张，等 turn-stopping/turn-start 冲刷`;
+                return true;
+            }
+            const written = appendMany(owner, turn, inputs);
+            lastPublishTrace = `owner=${owner.id} 回合打开(turn=${turn}) → ${written ? `已批量登记 ${inputs.length} 张` : '写入失败'}`;
+            return written;
+        },
         /** Diagnostics/tests: queued charts not yet flushed. */
         pendingCount(ownerSessionId) {
             if (ownerSessionId !== undefined)