@v587d/capital-generation 2.9.1 → 2.10.0

package/lib/chart/present-tool.d.ts

@@ -10,10 +10,18 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { ChartArtifactRegistry } from './artifact-ref.js';
 import { type ChartEventPublisher } from './events.js';
+import type { ChartDelivery } from './delivery.js';
+import type { SessionLike } from '../data-collector/store.js';
+/** One card can carry many files (the client collapses past four); the cap only bounds one event. */
+export declare const MAX_PRESENT_CHARTS = 32;
 export interface PresentChartsInput {
     artifacts: ChartArtifactRegistry;
     /** Lazy: the host projection may mount after this row; an absent publisher fails the call loudly. */
     chartEvents: () => ChartEventPublisher | undefined;
+    /** Records the selection; the closing stream chunk writes it (normal path). */
+    delivery?: ChartDelivery;
+    /** Fallback-only guard when the stream listener is unavailable. */
+    readiness?: (session: SessionLike) => Promise<string | undefined>;
 }
 export interface PresentChartsReceipt {
     presented: Array<{

package/lib/chart/present-tool.js

@@ -1,5 +1,7 @@
 import { MAX_CHARTS_PER_TURN } from './events.js';
 import { callerSession } from '../tool-exec.js';
+/** One card can carry many files (the client collapses past four); the cap only bounds one event. */
+export const MAX_PRESENT_CHARTS = 32;
 const jsonObject = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
 const parameters = jsonObject({
     chart_refs: {
@@ -41,8 +43,8 @@ function normalizeRefs(value) {
         if (!refs.includes(ref))
             refs.push(ref);
     }
-    if (refs.length > MAX_CHARTS_PER_TURN) {
-        throw new Error(`present_charts 一次最多登记 ${MAX_CHARTS_PER_TURN} 张图（收到 ${refs.length} 个 chart_ref）`);
+    if (refs.length > MAX_PRESENT_CHARTS) {
+        throw new Error(`present_charts 一次最多登记 ${MAX_PRESENT_CHARTS} 张图（收到 ${refs.length} 个 chart_ref）`);
     }
     return refs;
 }
@@ -53,6 +55,52 @@ function normalizeTaskId(value) {
         throw new Error('present_charts 的 task_id 必须是非空字符串');
     return value.trim();
 }
+const TITLE_SUBJECT_CODE = /(?<!\d)(\d{6})(?!\d)/g;
+function titleSubjectCodes(title) {
+    return [...title.matchAll(TITLE_SUBJECT_CODE)].map((match) => match[1]);
+}
+/** Strip six-digit codes and punctuation so “同花顺 300033 日K” and “同花顺 300803 日K” share a key. */
+function titleDedupeKey(title) {
+    return title
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(TITLE_SUBJECT_CODE, '')
+        .replace(/[\s\p{P}\p{S}]+/gu, '');
+}
+function artifactQualityFailure(artifact) {
+    const codes = titleSubjectCodes(artifact.title);
+    if (codes.length === 0 || artifact.subject_code === null)
+        return undefined;
+    const mismatched = [...new Set(codes.filter((code) => code !== artifact.subject_code))];
+    if (mismatched.length === 0)
+        return undefined;
+    return `标题里的股票代码 ${mismatched.join('、')} 与 dataset 对应的 ${artifact.subject_code} 不一致；请改正标题后重绘，未登记这张图`;
+}
+function dedupeArtifacts(artifacts) {
+    const kept = [];
+    const failed = [];
+    const seen = new Map();
+    for (const artifact of artifacts) {
+        const qualityFailure = artifactQualityFailure(artifact);
+        if (qualityFailure !== undefined) {
+            failed.push({ chart_ref: artifact.chart_ref, reason: qualityFailure });
+            continue;
+        }
+        const titleKey = titleDedupeKey(artifact.title);
+        const key = `${artifact.dataset_id ?? 'no-dataset'}|${artifact.kind}|${titleKey.length > 0 ? titleKey : artifact.chart_ref}`;
+        const previous = seen.get(key);
+        if (previous !== undefined) {
+            failed.push({
+                chart_ref: artifact.chart_ref,
+                reason: `重复图表：与 ${previous.chart_ref} 的 dataset/kind/标题相同；只登记第一张`,
+            });
+            continue;
+        }
+        seen.set(key, artifact);
+        kept.push(artifact);
+    }
+    return { kept, failed };
+}
 /** Present refs first; otherwise present the whole task so compaction cannot strand the charts. */
 function selectArtifacts(input, session, refs, taskId) {
     const failed = [];
@@ -75,9 +123,9 @@ function selectArtifacts(input, session, refs, taskId) {
     const all = input.artifacts.list({ session, task_id: taskId });
     if (all.length === 0)
         failed.push({ chart_ref: '(task)', reason: `本会话该 task_id 没有可登记的图表：${taskId}` });
-    const selected = all.slice(0, MAX_CHARTS_PER_TURN);
-    if (all.length > MAX_CHARTS_PER_TURN) {
-        failed.push({ chart_ref: '(task)', reason: `该 task_id 有 ${all.length} 张图，本轮最多登记 ${MAX_CHARTS_PER_TURN} 张；其余未展示` });
+    const selected = all.slice(0, MAX_PRESENT_CHARTS);
+    if (all.length > MAX_PRESENT_CHARTS) {
+        failed.push({ chart_ref: '(task)', reason: `该 task_id 有 ${all.length} 张图，单次最多登记 ${MAX_PRESENT_CHARTS} 张；其余未展示` });
     }
     return { selected, failed };
 }
@@ -87,10 +135,11 @@ export function registerPresentChartsTool(ctx, input) {
         return;
     const definition = {
         name: 'present_charts',
-        description: '把本会话已生成的图表登记为**最终答复的交付物**（官方 deliverables/presented）：用户会在本轮答复末尾的「本轮文件改动 / 交付」行看到卡片，点开即渲染自包含 chart.html。'
-            + '**只由主 Agent 在写最终答复前调用一次**：参数是 data_junior 回传的 chart_refs（一次全部传入，最多 8 个）；refs 已丢失时改传 task_id 登记该任务的全部图表；调用后立刻写最终答复。'
-            + '不要在过程轮 / 等待行前调用，不要分批重复调用；不要传文件路径或 HTML（路径由宿主解析）。'
-            + '不调用本工具，图表不会出现在对话里。',
+        description: '把本会话已生成的图表登记为**最终答复的交付物**（官方 deliverables/presented）：用户会在答复末尾的「本轮文件改动 / 交付」行看到卡片，点开即渲染自包含 HTML（文件名带代码/标题或图形类型，如 `300803-kline-<短id>.html`）。'
+            + '**由主 Agent 调用一次**：参数是 data_junior 回传的 chart_refs（一次传入，最多 32 个）；refs 已丢失时改传 task_id 登记该任务的全部图表。'
+            + '登记前会按 dataset + kind + 标题去重，并校验标题里的 6 位股票代码与 dataset 一致；重复或错标题的 ref 会进 failed，不会出现在交付卡片里。'
+            + '这里只记录本轮要交付的图，宿主会在**最终答复之前**统一写入交付行——提前调用不会落进中间轮，不必等“最后一刻”，也不要在过程轮反复调用。'
+            + '不要传文件路径或 HTML（路径由宿主解析）；不调用时宿主仍会在收尾时自动登记本 exchange 已生成的图表。',
         parameters,
         async execute(args, exec) {
             const session = callerSession(exec);
@@ -99,23 +148,44 @@ export function registerPresentChartsTool(ctx, input) {
             if (refs.length === 0 && taskId === undefined) {
                 throw new Error('present_charts 需要 chart_refs 或 task_id：两者都不给就无法确定要登记哪几张图');
             }
+            const { selected: selectedRaw, failed } = selectArtifacts(input, session, refs, taskId);
+            const { kept: selected, failed: qualityFailed } = dedupeArtifacts(selectedRaw);
+            failed.push(...qualityFailed);
+            const receipt = { presented: [], failed };
+            if (selected.length === 0)
+                return receipt;
+            const inputs = selected.map((artifact) => ({
+                ownerSessionId: session.id,
+                chart_id: artifact.chart_id,
+                title: artifact.title,
+                html_path: artifact.html_path,
+            }));
+            // Normal path: remember the selection; the closing stream chunk writes it before the answer.
+            if (input.delivery?.streaming() === true) {
+                input.delivery.request(session, inputs);
+                for (const artifact of selected)
+                    receipt.presented.push({ chart_ref: artifact.chart_ref, title: artifact.title });
+                return receipt;
+            }
+            // Fallback path (stream listener unavailable): write now, but only when the turn is idle.
+            const blocked = await input.readiness?.(session);
+            if (blocked !== undefined)
+                throw new Error(blocked);
             const publisher = input.chartEvents();
             if (publisher === undefined) {
-                throw new Error('图表交付通道不可用（sessions / sessionProjections 解析不到）：图表已落盘，可在 workspace 打开 chart.html');
+                throw new Error('图表交付通道不可用（sessions / sessionProjections 解析不到）：图表已落盘，可在 workspace 打开 html_path 指向的 HTML');
             }
-            const { selected, failed } = selectArtifacts(input, session, refs, taskId);
-            const receipt = { presented: [], failed };
-            for (const artifact of selected) {
-                const accepted = publisher.publish({
-                    ownerSessionId: session.id,
-                    chart_id: artifact.chart_id,
-                    title: artifact.title,
-                    html_path: artifact.html_path,
-                });
-                if (accepted)
+            const accepted = publisher.publishMany !== undefined
+                ? publisher.publishMany(session.id, inputs)
+                : inputs.every((item) => publisher.publish(item));
+            if (accepted) {
+                for (const artifact of selected)
                     receipt.presented.push({ chart_ref: artifact.chart_ref, title: artifact.title });
-                else
-                    receipt.failed.push({ chart_ref: artifact.chart_ref, reason: `本轮登记已达 ${MAX_CHARTS_PER_TURN} 张上限或回合已关闭，未写入交付行` });
+            }
+            else {
+                for (const artifact of selected) {
+                    receipt.failed.push({ chart_ref: artifact.chart_ref, reason: `本轮登记已达 ${MAX_CHARTS_PER_TURN} 次上限或回合已关闭，未写入交付行` });
+                }
             }
             return receipt;
         },

package/lib/chart/tool.js

@@ -16,6 +16,49 @@ function newChartId() {
     const suffix = cryptoLike?.randomUUID ? cryptoLike.randomUUID() : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
     return `ch_${suffix}`;
 }
+const SUBJECT_KEYS = ['thscode', 'ts_code', 'ticker', 'symbol', 'stock_code', 'sec_code', 'code'];
+/** Six-digit A-share/HK/US ticker; `thscode` wins over generic API status fields such as `code`. */
+function subjectCodeOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    for (const key of SUBJECT_KEYS) {
+        const raw = record[key];
+        if (typeof raw === 'string') {
+            const match = /(?<!\d)(\d{6})(?!\d)/.exec(raw);
+            if (match)
+                return match[1];
+        }
+        if (typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 100_000 && raw <= 999_999) {
+            return String(raw);
+        }
+    }
+    return null;
+}
+function chartSubjectCode(envelope, rows) {
+    const fromEnvelope = subjectCodeOf(envelope);
+    if (fromEnvelope !== null)
+        return fromEnvelope;
+    for (const row of rows.slice(0, 3)) {
+        const fromRow = subjectCodeOf(row);
+        if (fromRow !== null)
+            return fromRow;
+    }
+    return null;
+}
+/** Readable, collision-resistant filename: ASCII title slug + short chart id. The store's artifact
+ * name gate is deliberately ASCII, so Chinese titles fall back to the chart kind (code stays when
+ * the title/envelope carries one). */
+function chartHtmlName(title, kind, chartId, subjectCode) {
+    const kindSlug = kind === 'candlestick' ? 'kline' : kind === 'bar' ? 'ohlc' : kind === 'column' ? 'column' : kind === 'area' ? 'area' : 'line';
+    const words = title.normalize('NFKC').match(/[A-Za-z0-9]+/g) ?? [];
+    const parts = subjectCode !== null && !words.includes(subjectCode) ? [subjectCode, ...words] : [...words];
+    if (parts.length === 0 || (subjectCode !== null && parts.every((part) => part === subjectCode)))
+        parts.push(kindSlug);
+    const safe = parts.join('-').replace(/-+/g, '-').replace(/^[.\-]+|[.\-]+$/g, '').slice(0, 48);
+    const suffix = chartId.replace(/^ch_/, '').slice(0, 8);
+    return `${safe.length > 0 ? safe : kindSlug}-${suffix}.html`;
+}
 function sessionOf(exec) {
     const session = exec.agent?.session;
     if (!session || typeof session.id !== 'string' || session.id.length === 0) {
@@ -125,18 +168,27 @@ export async function renderChart(input, args, exec) {
         spec.title = args.title.trim().slice(0, 200);
     // The token carries the direct data-agent session; the nested child never sees raw rows.
     let rows;
+    let subjectCode;
     let meta;
     if (datasetId !== undefined) {
         const readSession = tokenSource?.sourceSession ?? session;
-        const { ref, rows: datasetRows } = await input.store.readPresentationRows({ session: readSession, dataset_id: datasetId, signal: exec.signal });
+        const { ref, rows: datasetRows, envelope } = await input.store.readPresentationRows({ session: readSession, dataset_id: datasetId, signal: exec.signal });
         rows = datasetRows;
-        meta = { source_kind: 'dataset', dataset_id: ref.dataset_id, source_label: ref.source_label, captured_at: ref.captured_at };
+        subjectCode = chartSubjectCode(envelope, datasetRows);
+        meta = {
+            source_kind: 'dataset',
+            dataset_id: ref.dataset_id,
+            source_label: ref.source_label,
+            captured_at: ref.captured_at,
+            ...(subjectCode === null ? {} : { subject_code: subjectCode }),
+        };
     }
     else {
         const parsed = await input.store.readWorkspaceJson({ session, path: path, signal: exec.signal });
         const extracted = extractRows(parsed);
         rows = extracted.rows;
-        meta = { source_kind: 'path' };
+        subjectCode = chartSubjectCode(parsed, extracted.rows);
+        meta = { source_kind: 'path', ...(subjectCode === null ? {} : { subject_code: subjectCode }) };
     }
     const chartId = newChartId();
     const payload = buildChartPayload({ chart_id: chartId, spec, rows, meta });
@@ -144,13 +196,14 @@ export async function renderChart(input, args, exec) {
     const generatedAt = now();
     const html = buildStandaloneHtml({ payload, library, generatedAt });
     const dir = `${CHART_ARTIFACT_DIR}/${chartId}`;
+    const htmlName = chartHtmlName(payload.title, payload.kind, chartId, subjectCode);
     const written = await input.store.writeWorkspaceFiles({
         session,
         dir,
         files: [
-            { name: 'spec.json', content: `${JSON.stringify({ chart_id: chartId, created_at: generatedAt, source: { dataset_id: meta.dataset_id ?? null, path: path ?? null }, spec }, null, 2)}\n` },
+            { name: 'spec.json', content: `${JSON.stringify({ chart_id: chartId, created_at: generatedAt, source: { dataset_id: meta.dataset_id ?? null, path: path ?? null, subject_code: subjectCode }, spec }, null, 2)}\n` },
             { name: 'series.json', content: `${JSON.stringify(payload)}\n` },
-            { name: 'chart.html', content: html },
+            { name: htmlName, content: html },
         ],
         signal: exec.signal,
     });
@@ -175,13 +228,14 @@ export async function renderChart(input, args, exec) {
         dataset_id: meta.dataset_id ?? null,
         source_label: meta.source_label ?? null,
         captured_at: meta.captured_at ?? null,
+        subject_code: subjectCode,
         kind: payload.kind,
         axis: payload.axis,
         title: payload.title,
         chart_url: chartUrl,
         spec_path: pathOf('spec.json'),
         series_path: pathOf('series.json'),
-        html_path: pathOf('chart.html'),
+        html_path: pathOf(htmlName),
         created_at: generatedAt,
     });
     // Unit callers without the registry still get a stable receipt.
@@ -202,7 +256,7 @@ export async function renderChart(input, args, exec) {
                 ownerSessionId,
                 chart_id: chartId,
                 title: payload.title,
-                html_path: pathOf('chart.html'),
+                html_path: pathOf(htmlName),
             });
             deliverableTrace = `publish=${accepted ? '受理' : '拒绝'} ownerSessionId=${ownerSessionId} | ${publisher.lastTrace?.() ?? '(无轨迹)'}`;
         }
@@ -242,7 +296,7 @@ export async function renderChart(input, args, exec) {
         chart_url: chartUrl,
         spec_path: pathOf('spec.json'),
         series_path: pathOf('series.json'),
-        html_path: pathOf('chart.html'),
+        html_path: pathOf(htmlName),
         warnings: payload.meta.warnings,
     };
 }
@@ -252,7 +306,7 @@ export function registerChartTool(ctx, options) {
         return;
     const definition = {
         name: 'render_chart',
-        description: `把已经取到的数据渲染成一张可交互图，产物落在 workspace 的 ${CHART_ARTIFACT_DIR}/<chart_id>/（chart.html 可离线打开）。` +
+        description: `把已经取到的数据渲染成一张可交互图，产物落在 workspace 的 ${CHART_ARTIFACT_DIR}/<chart_id>/（HTML 以标题/代码命名，如「600519-kline-<短id>.html」，可离线打开）。` +
             '**只回一条小回执，不回任何原始数据行**：序列走旁路，不进入上下文。' +
             '来源三选一：dataset_id（已授权的 DatasetRef）、path（workspace 相对路径的 JSON，支持顶层数组或含行数组的 envelope），或 chart_source_ref（宿主签发给 visualization_specialist 的短期 token；使用它时还要提供 task_id）。' +
             'spec 是自由对象，至少给出 kind（line / area / column / candlestick / bar；后两者要 ohlc 四字段与真实时间列）与字段选择（series 或 ohlc），' +

package/lib/data-collector/dataset-tools.js

@@ -364,7 +364,7 @@ export function registerDatasetTools(ctx, store, options = {}) {
                 withIsoTimeColumns(result, prepared.axis);
             return result;
         }),
-        tool('describe_dataset', `读取一份 Dataset 的**默认入口**：一次调用完成 inspect（元数据与可读性/形状）、profile（宿主算基础质量与四类事实，写入 profile_ref）与受控 query（可选）；原始 rows 不进入模型上下文。一次只处理一个 dataset_id——本轮有多份数据时，请在**同一条消息里一次发出多个调用**（本工具可并发执行，结果会一起返回），不要一份一份等。行集合返回：① 元数据 artifact_ref/capability/source_label/captured_at/retention_until 与 query_access.shape（array / envelope_item = 行集合；document = 顶层文档对象，只能 profile，queries 由宿主跳过）；② profile 四类事实——statistics（count/sum/min/max/mean/分位数）、categories（distinct + 最多 5 个高频取值）、time_facts（覆盖范围与首行/末行取值；回答"最新值、区间涨跌"必须用它，不要用 min/max 代替）、structure（嵌套路径摘要）；③ queries——每条的 QueryResult，或该条自己的 error（单条失败不影响其余）。columns_of_interest 只对这些列返回 statistics/categories/schema（并同样收窄 time_facts 的首末值投影，时间列永远保留），是收窄结果体积的唯一手段。结果超过 ${SAFE_RESULT_CHARS} 码点时宿主不返回超长载荷，而返回 {status:'too_large', profile_ref, columns, bytes, facts_bytes, queries_bytes, hint}：facts_bytes/queries_bytes 是体积归因（哪边大砍哪边），按 hint 重发一次即可——queries 大就先去掉 queries（聚合改单独走 query_dataset），facts 大就用 columns_of_interest 收窄列（或减少 queries，最多 ${MAX_DESCRIBE_QUERIES} 条）。单点复核仍可用 inspect_dataset / profile_dataset / query_dataset；不接受任何文件路径、脚本内容或自定义表达式。`, describeParametersSchema, describeResultSchema, async (args, exec) => describeDataset({
+        tool('describe_dataset', `读取一份 Dataset 的**默认入口**：一次调用完成 inspect（元数据与可读性/形状）、profile（宿主算基础质量与四类事实，写入 profile_ref）与受控 query（可选）；原始 rows 不进入模型上下文。一次只处理一个 dataset_id——本轮有多份数据时请并发调用本工具（PTC 在同一个 run_code 程序里用 Promise.all，native 在同一条消息里一次发出多个调用），不要一份一份等。行集合返回：① 元数据 artifact_ref/capability/source_label/captured_at/retention_until 与 query_access.shape（array / envelope_item = 行集合；document = 顶层文档对象，只能 profile，queries 由宿主跳过）；② profile 四类事实——statistics（count/sum/min/max/mean/分位数）、categories（distinct + 最多 5 个高频取值）、time_facts（覆盖范围与首行/末行取值；回答"最新值、区间涨跌"必须用它，不要用 min/max 代替）、structure（嵌套路径摘要）；③ queries——每条的 QueryResult，或该条自己的 error（单条失败不影响其余）。columns_of_interest 只对这些列返回 statistics/categories/schema（并同样收窄 time_facts 的首末值投影，时间列永远保留），是收窄结果体积的唯一手段。结果超过 ${SAFE_RESULT_CHARS} 码点时宿主不返回超长载荷，而返回 {status:'too_large', profile_ref, columns, bytes, facts_bytes, queries_bytes, hint}：facts_bytes/queries_bytes 是体积归因（哪边大砍哪边），按 hint 重发一次即可——queries 大就先去掉 queries（聚合改单独走 query_dataset），facts 大就用 columns_of_interest 收窄列（或减少 queries，最多 ${MAX_DESCRIBE_QUERIES} 条）。单点复核仍可用 inspect_dataset / profile_dataset / query_dataset；不接受任何文件路径、脚本内容或自定义表达式。`, describeParametersSchema, describeResultSchema, async (args, exec) => describeDataset({
             store,
             session: authorizedSession(ctx, exec, 'describe_dataset', DATASET_READING_PRESET_IDS),
             request: normalizeDescribeArgs(args),

package/lib/data-collector/store.d.ts

@@ -353,6 +353,7 @@ export declare class WorkspaceDatasetStore {
     }): Promise<{
         ref: DatasetRef;
         rows: unknown[];
+        envelope?: Record<string, unknown>;
     }>;
     /**
      * Host-internal workspace text read; with readWorkspaceBytes it shares containment and size

package/lib/data-collector/store.js

@@ -332,7 +332,7 @@ export class WorkspaceDatasetStore {
         if (raw.rows.length > maxRows) {
             throw new DatasetStoreError('dataset_too_large', `Dataset has ${raw.rows.length} rows; presentation reads are capped at ${maxRows}`);
         }
-        return { ref, rows: raw.rows };
+        return { ref, rows: raw.rows, ...(raw.envelope === undefined ? {} : { envelope: raw.envelope }) };
     }
     /**
      * Host-internal workspace text read; with readWorkspaceBytes it shares containment and size
@@ -500,7 +500,7 @@ export class WorkspaceDatasetStore {
         if (isRecord(value)) {
             const rows = rowsAtPath(value, rowKey ?? 'item');
             if (rows !== undefined)
-                return { kind: 'rows', rows, shape: 'envelope_item' };
+                return { kind: 'rows', rows, shape: 'envelope_item', envelope: value };
         }
         if (isRecord(value))
             return { kind: 'document', value };

package/lib/orchestration-entry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `tools/orchestration` row: the root-only `wait_for_agents` tool.
+ *
+ * Leaves don't mount this row: a child has no delegated tree to wait for and must use send_message
+ * to report upward. The tool also rejects the subagent origin at call time, so a mis-mounted row
+ * cannot turn into a child-side polling loop.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-orchestration-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/orchestration-entry.js

@@ -0,0 +1,6 @@
+import { registerWaitForAgentsTool } from './agents/wait-for-agents.js';
+export const name = 'capital-orchestration-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    registerWaitForAgentsTool(ctx);
+}

package/lib/present-entry.d.ts

@@ -1,9 +1,19 @@
 /**
- * `tools/present` row: present_charts only. The root Agent's final-turn delivery step — the
- * auto-mode chart pipeline returns refs upward and the main Agent redeems them here right before
- * writing the closing answer (rationale: docs/dev/chart-delivery-events.md §6.3).
+ * `tools/present` row: present_charts + the closing-answer delivery listener.
+ *
+ * The model only records which charts belong to the answer. The actual first-party
+ * `deliverables/presented` append happens in the terminal assistant-stream chunk, before the closing
+ * message commits, gated on an idle root (no actionable inbox input, no running direct children). That is the only
+ * point where "the final answer" is knowable, so early/no `present_charts` calls cannot strand the
+ * card in a folded process turn (rationale: docs/dev/chart-delivery-events.md §6.3).
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { SessionLike } from './data-collector/store.js';
 export declare const name = "capital-present-tools";
 export declare const inject: string[];
+/**
+ * Fallback only: when the stream listener never fires, immediate delivery still has to avoid a
+ * pending turn. The normal path defers to the closing stream chunk and does not consult this.
+ */
+export declare function chartDeliveryBlocker(ctx: Context, session: SessionLike): Promise<string | undefined>;
 export declare function apply(ctx: Context): void;

package/lib/present-entry.js

@@ -1,13 +1,135 @@
+import { createChartDelivery } from './chart/delivery.js';
 import { createChartEventPublisher } from './chart/events.js';
 import { chartEventContextOf } from './chart/event-context.js';
 import { registerPresentChartsTool } from './chart/present-tool.js';
+import { createSettledWakeGuard } from './agents/settled-wake.js';
 import { capitalSharedRuntimeOf } from './chart-source-entry.js';
 export const name = 'capital-present-tools';
 export const inject = ['tools'];
+/**
+ * Fallback only: when the stream listener never fires, immediate delivery still has to avoid a
+ * pending turn. The normal path defers to the closing stream chunk and does not consult this.
+ */
+export async function chartDeliveryBlocker(ctx, session) {
+    const projections = ctx.get('sessionProjections');
+    try {
+        const inbox = projections?.stateOf(session, 'inbox');
+        // A settlement notice can race the closing answer; it must not block the card. Any relay or
+        // human input still means another model step is pending.
+        const pending = [...(inbox?.['next-turn'] ?? []), ...(inbox?.['next-step'] ?? [])]
+            .filter((message) => {
+            const source = message?.source;
+            return source?.kind !== 'subagent-settled';
+        }).length;
+        if (pending > 0) {
+            return `还有 ${pending} 条待处理消息（子 Agent 回传 / 结算）：现在登记会让卡片留在被折叠的中间轮。`
+                + '等这些消息处理完、写最终答复的那一步再调用 present_charts（refs 记不清就传 task_id）。';
+        }
+    }
+    catch {
+        // Projection unavailable: delivery availability matters more than the guard.
+    }
+    const subagents = ctx.get('subagents');
+    if (typeof subagents?.listDescendants === 'function') {
+        try {
+            const rows = await subagents.listDescendants(session.id);
+            const running = rows.filter((row) => row?.kind === 'child' && row?.activity === 'running').length;
+            if (running > 0) {
+                return `还有 ${running} 个子 Agent 在运行：现在登记会让卡片留在被折叠的中间轮。`
+                    + '等它们全部结算、写最终答复的那一步再调用 present_charts（refs 记不清就传 task_id）。';
+            }
+        }
+        catch {
+            // Subagent service unavailable: don't block delivery for a missing optional check.
+        }
+    }
+    return undefined;
+}
+function inboxOf(ctx) {
+    const projections = ctx.get('sessionProjections');
+    return (session) => {
+        try {
+            return projections?.stateOf(session, 'inbox');
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
 export function apply(ctx) {
     const shared = capitalSharedRuntimeOf(ctx);
+    const publisherOf = () => createChartEventPublisher(chartEventContextOf(ctx));
+    const eventCtx = ctx;
+    const wakeGuard = createSettledWakeGuard();
+    const delivery = createChartDelivery({
+        artifacts: shared.artifacts,
+        publish: (sessionId, inputs) => publisherOf()?.publishMany(sessionId, inputs) ?? false,
+        inboxOf: inboxOf(ctx),
+        onClosing: (_session, agent) => wakeGuard.acceptClosing(agent),
+    });
+    // The preset row is applied in the root agent's scope: these events are the root's own.
+    const disposers = [];
+    if (typeof eventCtx.on === 'function') {
+        disposers.push(eventCtx.on('agent/assistant-stream', (...args) => {
+            const payload = args[0];
+            if (payload?.frame === undefined)
+                return;
+            delivery.acceptStream(payload.agent?.session, payload.frame, payload.agent);
+        }));
+        disposers.push(eventCtx.on('subagent/start', (...args) => {
+            const info = args[0];
+            delivery.acceptSubagentStart(info ?? {});
+            wakeGuard.acceptSubagentStart(info ?? {});
+        }));
+        disposers.push(eventCtx.on('subagent/end', (...args) => delivery.acceptSubagentEnd(args[0])));
+        // Scoped to the root agent: only the root inbox is inspected. A settled notice inserted after
+        // the closing frame would otherwise make the loop open a step for a redundant "done" message.
+        disposers.push(eventCtx.on('agent/inbox/inserted', (...args) => {
+            const payload = args[0];
+            if (payload?.agent === undefined || payload.message === undefined)
+                return;
+            wakeGuard.acceptInboxInserted(payload.agent, payload.message);
+        }));
+    }
+    // Session events are not agent-scoped: listen on the unscoped root and filter by payload.
+    const listen = (eventCtx.root ?? ctx);
+    if (typeof listen.on === 'function') {
+        disposers.push(listen.on('session/event', (...args) => {
+            const session = args[0];
+            const event = args[1];
+            if (event?.type !== 'user/message')
+                return;
+            const source = event.data?.source;
+            // The settlement notice is authoritative even when the lifecycle edge was missed; clearing
+            // here keeps the stream-time idle check from waiting on a child that is already done.
+            if (source?.kind === 'subagent-settled') {
+                if (typeof source.senderSessionId === 'string')
+                    delivery.acceptSubagentEnd({ id: source.senderSessionId });
+                return;
+            }
+            if (typeof session?.id !== 'string' || source === undefined)
+                return;
+            if (source.kind === 'user') {
+                delivery.acceptUserMessage(session.id, typeof event.time === 'number' ? event.time : Date.now());
+                wakeGuard.acceptUserMessage(session, source);
+                return;
+            }
+            // `user/message` is committed only when admitted, so this is exactly the "child already
+            // reported its result" marker the closing guard needs.
+            if (source.kind === 'agent-message')
+                wakeGuard.acceptUserMessage(session, source);
+        }));
+    }
+    ctx.effect(() => () => {
+        for (const dispose of disposers) {
+            if (typeof dispose === 'function')
+                dispose();
+        }
+    }, 'capital-generation.chart-delivery()');
     registerPresentChartsTool(ctx, {
         artifacts: shared.artifacts,
-        chartEvents: () => createChartEventPublisher(chartEventContextOf(ctx)),
+        chartEvents: publisherOf,
+        readiness: (session) => chartDeliveryBlocker(ctx, session),
+        delivery,
     });
 }

package/lib/web-retriever/local-fetch.d.ts

@@ -3,7 +3,7 @@
  * Known limit: DNS resolves per request but the IP is not pinned to the connection,
  * so a rebinding window remains (same trade-off as dsh-search-first).
  */
-export declare const LOCAL_FETCH_CLIENT_VERSION = "2.9.1";
+export declare const LOCAL_FETCH_CLIENT_VERSION = "2.10.0";
 export declare const LOCAL_FETCH_MAX_URL_LENGTH = 2048;
 export type LocalFetchErrorCode = 'ABORTED' | 'TIMEOUT' | 'INVALID_URL' | 'BLOCKED_URL' | 'DNS' | 'REDIRECT' | 'HTTP' | 'TOO_LARGE' | 'UNSUPPORTED_CONTENT_TYPE';
 export declare class LocalFetchError extends Error {

package/lib/web-retriever/local-fetch.js

@@ -4,7 +4,7 @@
  * so a rebinding window remains (same trade-off as dsh-search-first).
  */
 import { htmlToMarkdown, stripInvisibleText } from './html-markdown.js';
-export const LOCAL_FETCH_CLIENT_VERSION = '2.9.1';
+export const LOCAL_FETCH_CLIENT_VERSION = '2.10.0';
 export const LOCAL_FETCH_MAX_URL_LENGTH = 2048;
 export class LocalFetchError extends Error {
     code;

package/lib/web-retriever/wind-client.d.ts

@@ -35,7 +35,7 @@ export interface WindCallResult {
     code?: WindErrorCode;
 }
 /** Must match `package.json` version; a test pins the two together. */
-export declare const WIND_CLIENT_VERSION = "2.9.1";
+export declare const WIND_CLIENT_VERSION = "2.10.0";
 export interface WindClient {
     callTool(toolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<WindCallResult>;
 }

package/lib/web-retriever/wind-client.js

@@ -19,7 +19,7 @@ export const WIND_SERVER_ENDPOINTS = {
     analytics_data: 'https://mcp.wind.com.cn/vserver_analytics_data/mcp/',
 };
 /** Must match `package.json` version; a test pins the two together. */
-export const WIND_CLIENT_VERSION = '2.9.1';
+export const WIND_CLIENT_VERSION = '2.10.0';
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/capital-generation",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "Capital Generation：面向中国散户的 AI 投资助手插件（自动模式 Agent Preset）",
   "icon": "assets/cg-icon.png",
   "author": "v587d",
@@ -57,6 +57,11 @@
       "import": "./lib/ocr-entry.js",
       "default": "./lib/ocr-entry.js"
     },
+    "./tools/orchestration": {
+      "types": "./lib/orchestration-entry.d.ts",
+      "import": "./lib/orchestration-entry.js",
+      "default": "./lib/orchestration-entry.js"
+    },
     "./tools/present": {
       "types": "./lib/present-entry.d.ts",
       "import": "./lib/present-entry.js",
@@ -140,7 +145,8 @@
     "contract:probe": "node scripts/contract-probe.mjs",
     "docs:capabilities": "npm run build && node scripts/gen-capability-table.mjs",
     "verify:sessions": "node scripts/verify-sessions.mjs",
-    "audit:tool-errors": "node scripts/audit-tool-errors.mjs"
+    "audit:tool-errors": "node scripts/audit-tool-errors.mjs",
+    "ptc:report": "node scripts/ptc-session-report.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",