dsh-subagent-profile 0.3.0 → 0.3.2

package/lib/core/catalog-cache.mjs

@@ -0,0 +1,235 @@
+// lib/core/catalog-cache.mjs — 进程级共享 catalog 快照：一次拉取 llm 目录
+// （providers + 每 provider 的 models + 每模型 reasoning-effort 等级）、
+// system-trust 预设名册与完整工具目录，按 TTL 缓存后同时喂给设置页 /options
+// 三路由与 dispatch 的 cost guard。TTL 过期自动重拉；同 key 在途 Promise 去重；
+// /options/refresh 手动清缓存兜底。
+//
+// 依赖边界（无 @deepseek-ai 依赖）：仅 import 纯数据表
+// lib/core/catalog.mjs（工具名 → 中文/分类，零依赖）。服务经注入 getter 传入：
+//   getLlm          () => ctx.get('llm')           （headless 下可为 undefined）
+//   getAgentPresets  () => ctx.get('agentPresets')
+//   getTools         () => ctx.tools
+// cost guard 校验的是「父 Agent 的 llm 实例」；同一进程内父 ctx 与插件 ctx 读到的
+// 是同一个 host llm 服务，故 getSnapshot 接受可选 llm 覆盖（父实例）时仍命中同一条目。
+//
+// 缓存只提速目录解析，不复检安全门：provider/model/reasoningEffort 的校验逻辑与
+// fail-loud 文案留在 lib/core/cost-guard.mjs（逐字不变），此处仅提供目录数据。
+
+import { TOOL_ZH, TOOL_CATEGORY } from './catalog.mjs';
+
+const DEFAULT_TTL_MS = 60000;
+
+// --- 目录构建（无缓存；行为与 http-routes 原 collector 逐字一致）----------------
+
+// llm 目录：providers + 每 provider models + 每模型 efforts。listProviders 失败
+// 记入 providersError（cost guard 据此判「目录为空」）；每 provider 的 listModels
+// 失败单独记录——cost guard 需要区分「空目录短路」与「listModels 抛错」的 fail-loud 文案。
+async function collectLlmDirectory(llm) {
+  const models = [];
+  const efforts = Object.create(null);
+  const modelsByProvider = Object.create(null);
+  if (llm === undefined || typeof llm.listProviders !== 'function') {
+    return { providersError: undefined, providers: [], modelsByProvider, models, efforts };
+  }
+  let providers;
+  let providersError;
+  try {
+    providers = (await llm.listProviders()) ?? [];
+  } catch (error) {
+    providersError = error instanceof Error ? error : new Error(String(error));
+    return { providersError, providers: [], modelsByProvider, models, efforts };
+  }
+  for (const provider of providers) {
+    const providerId = provider && provider.id;
+    if (typeof providerId !== 'string') continue;
+    let entry;
+    try {
+      const modelList = await llm.listModels(providerId);
+      entry = { ok: true, models: modelList ?? [] };
+    } catch (error) {
+      entry = { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+    modelsByProvider[providerId] = entry;
+    if (entry.ok !== true) continue; // 该 provider 目录拉取失败 → 跳过其 UI 目录
+    for (const model of entry.models) {
+      if (!model || typeof model.id !== 'string') continue;
+      models.push({ provider: providerId, providerName: provider.name ?? providerId, id: model.id, name: model.name ?? model.id });
+      try {
+        const info = await llm.resolveModelInfo(providerId, model.id);
+        const effortsList = info && info.reasoning && Array.isArray(info.reasoning.efforts) ? info.reasoning.efforts : [];
+        efforts[model.id] = effortsList.map((effort) => ({
+          id: effort.id,
+          name: effort.name ?? effort.id,
+          ...(effort.description !== undefined ? { description: effort.description } : {})
+        }));
+      } catch { /* 精确模型查询可能拒绝；跳过其 efforts */ }
+    }
+  }
+  return { providersError: undefined, providers, modelsByProvider, models, efforts };
+}
+
+// System-trust 预设名册（agentPresets 可选，fail-soft）。
+async function collectSystemPresets(agentPresets) {
+  const presets = [];
+  if (agentPresets === undefined || typeof agentPresets.list !== 'function') return presets;
+  try {
+    const list = await agentPresets.list();
+    for (const preset of (list ?? [])) {
+      if (preset && preset.trust === 'system') {
+        presets.push({ id: preset.id, name: preset.name ?? preset.id });
+      }
+    }
+  } catch { /* presets roster unavailable; leave empty */ }
+  return presets;
+}
+
+// 完整工具目录 = global 层（部署插件）+ 每个 preset 的 standing scope
+// （agent.cordis.yml 工具行）。工具按其来源打标：'global' 或 preset id——分组完全
+// 动态，源自运行时名册。整体失败 fail-soft（返回空目录 + 告警），不破坏设置页。
+async function collectToolsDirectory(getTools, getAgentPresets, logger) {
+  try {
+    const tools = [];
+    const seen = new Set();
+    const OFFICIAL_PRESETS = ['standard', 'code', 'minimal', 'cordis'];
+    const layerOf = (source) => {
+      if (source === 'global') return 'plugin';
+      if (OFFICIAL_PRESETS.includes(source)) return 'core';
+      return 'custom';
+    };
+    const groupOf = (name, source) => {
+      const layer = layerOf(source);
+      if (layer === 'core') return TOOL_CATEGORY[name] ?? '其他';
+      if (layer === 'plugin') return name.includes('_') ? name.split('_')[0] : name;
+      return source;
+    };
+    const push = (schemas, source) => {
+      for (const s of (Array.isArray(schemas) ? schemas : [])) {
+        if (!s || typeof s.name !== 'string' || s.name === 'run_code' || seen.has(s.name)) continue;
+        seen.add(s.name);
+        tools.push({ name: s.name, description: typeof s.description === 'string' ? s.description : '', zh: TOOL_ZH[s.name] ?? '', source, layer: layerOf(source), group: groupOf(s.name, source) });
+      }
+    };
+    const toolsService = typeof getTools === 'function' ? getTools() : undefined;
+    if (toolsService && typeof toolsService.schemas === 'function') {
+      push(toolsService.schemas(), 'global');
+      const agentPresets = typeof getAgentPresets === 'function' ? getAgentPresets() : undefined;
+      if (agentPresets !== undefined && typeof agentPresets.list === 'function' && typeof agentPresets.standingKeyFor === 'function') {
+        const presets = await agentPresets.list();
+        for (const preset of (presets ?? [])) {
+          if (!preset || typeof preset.id !== 'string') continue;
+          try {
+            push(toolsService.schemas(await agentPresets.standingKeyFor(preset.id)), preset.id);
+          } catch { /* 单个 preset 的 standing scope 不可用；跳过 */ }
+        }
+      }
+    }
+    return tools;
+  } catch (error) {
+    if (logger !== undefined && typeof logger.warn === 'function') {
+      logger.warn('[dsh-subagent-profile] tools directory failed:', error instanceof Error ? error.message : String(error));
+    }
+    return [];
+  }
+}
+
+// 构建一份完整快照（无缓存）。`llm` 可选：cost guard 用它传入父 Agent 的 llm 实例。
+export async function getCatalogSnapshot({ getLlm, getAgentPresets, getTools, llm, logger }) {
+  const effectiveLlm = llm !== undefined ? llm : (typeof getLlm === 'function' ? getLlm() : undefined);
+  const agentPresets = typeof getAgentPresets === 'function' ? getAgentPresets() : undefined;
+  const dir = await collectLlmDirectory(effectiveLlm);
+  const presets = await collectSystemPresets(agentPresets);
+  const tools = await collectToolsDirectory(getTools, getAgentPresets, logger);
+  return {
+    llm: { providersError: dir.providersError, providers: dir.providers, modelsByProvider: dir.modelsByProvider },
+    models: dir.models,
+    efforts: dir.efforts,
+    presets,
+    tools,
+  };
+}
+
+// --- TTL 缓存（按 llm 实例分键；同 key 在途去重；hit/miss 计数走 host logger）----
+
+const NO_LLM = Symbol('catalog-cache:no-llm');
+
+function makeAudit(logger) {
+  if (logger !== undefined && typeof logger.info === 'function') {
+    return (outcome, hits, misses) => logger.info(`[dsh-subagent-profile] catalog cache ${outcome} (hit=${hits}, miss=${misses})`);
+  }
+  return () => {};
+}
+
+// 命中/未命中判定 + TTL 过期重拉；并发 cache-miss 复用同一条在途 Promise（只拉一次）。
+async function resolveSnapshot(state, llm) {
+  // 无参时按注入的 getLlm() 取 llm 实例作 key——保证 /options 侧（无参）与
+  // cost guard 侧（传父实例）在同一 host llm 实例下命中同一条目。
+  const effectiveLlm = llm !== undefined ? llm : (typeof state.getLlm === 'function' ? state.getLlm() : undefined);
+  const key = effectiveLlm !== undefined ? effectiveLlm : NO_LLM;
+  const at = state.clock();
+  const entry = state.entries.get(key);
+  if (entry !== undefined) {
+    if (entry.snapshot !== undefined && entry.expiresAt > at) {
+      state.hits += 1;
+      state.audit('hit', state.hits, state.misses);
+      return entry.snapshot;
+    }
+    if (entry.inflight !== undefined) {
+      state.hits += 1;
+      state.audit('hit', state.hits, state.misses);
+      return entry.inflight;
+    }
+  }
+  state.misses += 1;
+  state.audit('miss', state.hits, state.misses);
+  const inflight = getCatalogSnapshot({
+    getLlm: state.getLlm,
+    getAgentPresets: state.getAgentPresets,
+    getTools: state.getTools,
+    llm: effectiveLlm,
+    logger: state.logger,
+  });
+  const fresh = { expiresAt: at + state.ttl, snapshot: undefined, inflight };
+  state.entries.set(key, fresh);
+  try {
+    const snapshot = await inflight;
+    fresh.snapshot = snapshot;
+    fresh.inflight = undefined;
+    // 目录错误态不缓存：providersError 意味着 listProviders 瞬时失败或目录为空，
+    // 缓存会让瞬时故障自愈延迟一个 TTL；每次重试既保持安全门保守又恢复更快。
+    if (snapshot.llm.providersError !== undefined) {
+      state.entries.delete(key);
+    }
+    return snapshot;
+  } catch (error) {
+    fresh.inflight = undefined;
+    state.entries.delete(key);
+    throw error;
+  }
+}
+
+function invalidateSnapshot(state, llm) {
+  if (llm !== undefined) state.entries.delete(llm);
+  else state.entries.clear();
+}
+
+// 工厂返回 { getSnapshot, invalidate, stats }。getSnapshot(llm?) 接受可选 llm 覆盖；
+// 无参时走注入的 getLlm()。stats() 供审计/测试读取 hit/miss 计数。
+export function createCatalogCache({ getLlm, getAgentPresets, getTools, logger, ttlMs, now }) {
+  const state = {
+    getLlm,
+    getAgentPresets,
+    getTools,
+    logger,
+    ttl: typeof ttlMs === 'number' && ttlMs > 0 ? ttlMs : DEFAULT_TTL_MS,
+    clock: typeof now === 'function' ? now : () => Date.now(),
+    entries: new Map(),
+    hits: 0,
+    misses: 0,
+    audit: makeAudit(logger),
+  };
+  return {
+    getSnapshot: (llm) => resolveSnapshot(state, llm),
+    invalidate: (llm) => invalidateSnapshot(state, llm),
+    stats: () => ({ hits: state.hits, misses: state.misses }),
+  };
+}

package/lib/core/catalog.mjs

@@ -1,6 +1,6 @@
-// lib/core/catalog.mjs — settings-page data tables moved verbatim from index.mjs
+// lib/core/catalog.mjs — settings-page data tables moved verbatim from index.mjs
 // (import-free, no @deepseek-ai dependency — node builtins only, none used
-// here). The /options tool-directory builder itself lives in lib/core/http-routes.mjs:
+// here). The /options tool-directory builder itself lives in lib/core/catalog-cache.mjs:
 // it reads ctx.tools/agentPresets (non-pure), so it is not part of this module.
 
 // Tool-name → 中文说明 map, shown beside the raw tool name in the toolFilter

package/lib/core/cost-guard.mjs

@@ -1,6 +1,6 @@
-// lib/core/cost-guard.mjs — 运行时推导的 cost guard，从 index.mjs 逐字拆出。
+// lib/core/cost-guard.mjs — 运行时推导的 cost guard，从 index.mjs 逐字拆出。
 // 仅引用 lib/core/pure.mjs 的 assertHardLimits；无 @deepseek-ai 依赖。
-
+//
 // 运行时推导的 cost guard，两部分：
 //   ① always-on hard caps (assertHardLimits, in lib/core/pure.mjs) — maxTokens /
 //      maxDepth are hard delegation caps, independent of the `llm` service, so
@@ -13,11 +13,15 @@
 //      fail-open compat (warn + skip; v1 数据迁移中) or fail-loud reject. A
 //      profile that requests none of provider/model/reasoningEffort has nothing
 //      to verify and always passes (valid in a headless deployment).
+//
+// 目录读取改走共享 catalog 快照（lib/core/catalog-cache.mjs）：assertCostGuard 的
+// `catalog` 参数是缓存实例，`catalog.getSnapshot(llm)` 返回缓存过的 providers /
+// modelsByProvider。缓存只提速目录解析、不复检安全门——provider/model/effort 的
+// 校验逻辑与 fail-loud 文案逐字不变；reasoningEffort 走直连 resolveCallConfig
+// （校验调用，非目录读取，不入缓存）。
 // Used by both the provider's authoritative check and the dispatch tool's
 // pre-check. `allowFailOpen`/`logger` are injected because this function is
 // module-scoped and cannot reach the apply closure's `allowFailOpen`/`ctx.logger`.
-//
-// ①-⑥ 校验段按行门抽为模块级私有纯函数（行为逐字不变）。
 
 import { assertHardLimits } from './pure.mjs';
 
@@ -29,22 +33,19 @@ function needsLlmCheck(profile) {
   );
 }
 
-// ③ 目录为空检测：llm 存在但其 provider 目录为空（无发现能力）→ 无法核验。
-// 读取失败同样视为空目录（保守，随后走 allowFailOpen 门）。
-async function isLlmDirectoryEmpty(llm) {
-  try {
-    const providers = await llm.listProviders();
-    return (providers ?? []).length === 0;
-  } catch {
-    return true;
+// llm 缺失或目录为空时统一走 allowFailOpen 门（fail-open warn 或 fail-loud 拒绝）。
+function handleUnverifiable(allowFailOpen, logger) {
+  if (allowFailOpen === true) {
+    logger.warn('llm 不可用：fail-open 兼容模式（v1 数据迁移中，建议保存一次配置以升级到 fail-loud）');
+    return;
   }
+  throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
 }
 
-// ④ provider 注册校验（目录非空时才能判定「不在目录」）。
-async function assertProviderRegistered(llm, profile) {
+// ④ provider 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
+function assertProviderRegistered(dir, profile) {
   if (typeof profile.provider !== 'string' || profile.provider.length === 0) return;
-  const providers = await llm.listProviders();
-  if (!(providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
+  if (!(dir.providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
     throw new Error(`dispatch: provider "${profile.provider}" is not a registered provider`);
   }
 }
@@ -56,13 +57,25 @@ async function assertProviderRegistered(llm, profile) {
 //    per-provider 空目录。A non-empty catalog that does not advertise the model
 //    fails loud. An unverifiable lookup (listModels(undefined) when no provider
 //    is known) becomes a clean fail-loud error instead of leaking "undefined".
-async function assertModelAdvertised(llm, profile, effectiveProvider) {
+//    modelsByProvider 来自快照；快照未覆盖的 provider（undefined / 不在名册）
+//    走直连 listModels 兜底，保持原 fail-loud 文案逐字。
+async function assertModelAdvertised(llm, profile, effectiveProvider, modelsByProvider) {
   if (typeof profile.model !== 'string' || profile.model.length === 0) return;
+  const cached = modelsByProvider !== undefined ? modelsByProvider[String(effectiveProvider)] : undefined;
   let models;
-  try {
-    models = await llm.listModels(effectiveProvider);
-  } catch (error) {
-    throw new Error(`dispatch: cannot validate model "${profile.model}" without a provider: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  let modelsError;
+  if (cached !== undefined) {
+    if (cached.ok === true) models = cached.models;
+    else modelsError = cached.error;
+  } else {
+    try {
+      models = await llm.listModels(effectiveProvider);
+    } catch (error) {
+      modelsError = error;
+    }
+  }
+  if (modelsError !== undefined) {
+    throw new Error(`dispatch: cannot validate model "${profile.model}" without a provider: ${modelsError instanceof Error ? modelsError.message : String(modelsError)}`, { cause: modelsError });
   }
   const listed = models ?? [];
   const known = listed.length > 0 && listed.some((model) => model && (model.id === profile.model || model.name === profile.model));
@@ -81,7 +94,7 @@ async function assertReasoningSupported(llm, profile, effectiveProvider, effecti
   }
 }
 
-export async function assertCostGuard(parent, profile, allowFailOpen, logger) {
+export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog) {
   // ① 硬上限 always-on（不依赖 llm）。
   assertHardLimits(profile.maxTokens, profile.maxDepth);
 
@@ -89,20 +102,21 @@ export async function assertCostGuard(parent, profile, allowFailOpen, logger) {
   if (!needsLlmCheck(profile)) return;
 
   const llm = parent.ctx.get('llm');
-  // ③ llm 缺失或目录为空 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
-  if (llm === undefined || await isLlmDirectoryEmpty(llm)) {
-    if (allowFailOpen === true) {
-      logger.warn('llm 不可用：fail-open 兼容模式（v1 数据迁移中，建议保存一次配置以升级到 fail-loud）');
-      return;
-    }
-    throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
+  // ③ llm 缺失 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
+  if (llm === undefined) return handleUnverifiable(allowFailOpen, logger);
+
+  // llm 存在：目录读取走共享 catalog 快照（缓存只提速目录解析，校验逻辑不变）。
+  const snapshot = await catalog.getSnapshot(llm);
+  const dir = snapshot.llm;
+  if (dir.providersError !== undefined || dir.providers.length === 0) {
+    return handleUnverifiable(allowFailOpen, logger);
   }
 
   // ④ provider 注册校验。
-  await assertProviderRegistered(llm, profile);
+  assertProviderRegistered(dir, profile);
   const effectiveProvider = profile.provider !== undefined ? profile.provider : parent.options.provider;
   const effectiveModel = profile.model !== undefined ? profile.model : parent.options.model;
   // ⑤ model 校验 + ⑥ reasoningEffort 校验。
-  await assertModelAdvertised(llm, profile, effectiveProvider);
+  await assertModelAdvertised(llm, profile, effectiveProvider, dir.modelsByProvider);
   await assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel);
 }

package/lib/core/delegation.mjs

@@ -1,4 +1,4 @@
-// lib/core/delegation.mjs — background one-shot settling + delegation metadata
+// lib/core/delegation.mjs — background one-shot settling + delegation metadata
 // assembly, moved from index.mjs. Local lib references only: imports
 // stopReasonError / withPartialText / textFrom from lib/core/pure.mjs (the shipped
 // shims.readResult is NOT used by settleStart — it is used only by the
@@ -7,6 +7,52 @@
 
 import { stopReasonError, withPartialText, textFrom } from './pure.mjs';
 
+// 子 Agent 会话的真实计费 token 五段分解：累加 session.events 里每条
+// assistant/message 事件携带的 provider usage（inputTokens / outputTokens /
+// cacheReadTokens / cacheWriteTokens / reasoningTokens）。这是宿主 dsh-llm
+// assembler 产出、dsh-session-stats 同源读取的真实计费口径，与
+// childTotalTokens（tokenMeter 对 surface 的字符密度启发式估算）并存：前者是
+// provider 实际报告的用量，后者是估算值，二者语义不同、互不替代。任何字段缺失
+// 按 0 累加；可选字段（缓存读/写/推理）全程无一条事件报告时省略该键；无任何
+// 事件带 usage 时返回 undefined（调用方不写 meta，向前兼容）。非 object / 非
+// number 一律忽略（fail-soft），使累加绝不阻断派发结算。
+//
+// 只累加 assistant/message：assistant/chunk 的 usage 是同一 step 的早期分片、
+// 随后会被该 step 的 message 事件替换——两者都累加会重复计数（若未来改成
+// 前缀匹配或累加 chunk，此守卫必须同步改并补测试）。
+export function collectChildUsage(session) {
+  if (session === undefined || session === null) return undefined;
+  const events = session.events;
+  if (!Array.isArray(events)) return undefined;
+  const totals = { inputTokens: 0, outputTokens: 0 };
+  const optionalTotals = { cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+  const seenOptional = new Set();
+  let anyUsage = false;
+  for (const event of events) {
+    if (event === null || typeof event !== 'object' || event.type !== 'assistant/message') continue;
+    const usage = event.data?.usage;
+    if (usage === null || typeof usage !== 'object' || Array.isArray(usage)) continue;
+    anyUsage = true;
+    for (const key of ['inputTokens', 'outputTokens']) {
+      const value = usage[key];
+      if (typeof value === 'number' && Number.isFinite(value) && value >= 0) totals[key] += value;
+    }
+    for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+      const value = usage[key];
+      if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+        optionalTotals[key] += value;
+        seenOptional.add(key);
+      }
+    }
+  }
+  if (!anyUsage) return undefined;
+  const out = { inputTokens: totals.inputTokens, outputTokens: totals.outputTokens };
+  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
+    if (seenOptional.has(key)) out[key] = optionalTotals[key];
+  }
+  return out;
+}
+
 // Settle one background one-shot run into a job outcome with the same
 // observability metadata the foreground path reports. Non-completed stop reasons
 // become failed (aborted => killed, shipped vocabulary) with partial output
@@ -14,19 +60,43 @@ import { stopReasonError, withPartialText, textFrom } from './pure.mjs';
 // `prune` is the result-recycle pre-clipper: the caller (dispatch
 // execute) injects a closure that calls the host toolResultPruner.pruneContent
 // before textFrom; defaulting to identity keeps the background path safe when no
-// pruner is available.
-export async function settleStart(start, signal, meta, prune = (blocks) => blocks) {
+// pruner is available. `t0` is the dispatch execute entry timestamp; the settled
+// outcome carries `elapsedMs = now - t0` and the underlying `stopReason` (the
+// shipped terminal vocabulary). Defaulting t0 to now keeps direct callers (tests)
+// working without threading a timestamp.
+export async function settleStart(start, signal, meta, prune = (blocks) => blocks, measureChild = () => undefined, t0 = Date.now()) {
   let run;
   try {
     run = await start;
     const result = await run.result;
     const failure = stopReasonError(result);
     if (failure !== undefined) {
-      return { status: result.stopReason === 'aborted' ? 'killed' : 'failed', detail: withPartialText(failure, result.output), ...meta };
+      return {
+        status: result.stopReason === 'aborted' ? 'killed' : 'failed',
+        detail: withPartialText(failure, result.output),
+        ...meta,
+        elapsedMs: Date.now() - t0,
+        stopReason: result.stopReason
+      };
     }
-    return { status: 'completed', output: textFrom(prune(result.output)), ...meta };
+    // 仅 completed 结算时测量（非 completed 走上方失败分支，不测）；在 dispose
+    // 之前读子 session，保证测量拿到完整事件流。measureChild 缺失/失败返回
+    // undefined → 省略字段（fail-soft）；childUsage 同样只在可累加时携带。
+    const childSession = run.localAgent?.session;
+    const childTotalTokens = measureChild(childSession);
+    const childUsage = collectChildUsage(childSession);
+    const metaOut = {
+      ...meta,
+      ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+      ...(childUsage !== undefined ? { childUsage } : {}),
+      elapsedMs: Date.now() - t0,
+      stopReason: 'completed'
+    };
+    return { status: 'completed', output: textFrom(prune(result.output)), ...metaOut };
   } catch (error) {
-    return signal.aborted ? { status: 'killed', ...meta } : { status: 'failed', detail: String(error), ...meta };
+    return signal.aborted
+      ? { status: 'killed', ...meta, elapsedMs: Date.now() - t0, stopReason: 'aborted' }
+      : { status: 'failed', detail: String(error), ...meta, elapsedMs: Date.now() - t0, stopReason: 'error' };
   } finally {
     // Release the child handle no matter how the result settled — run.result
     // rejecting must not leak the subagent (same discipline as the foreground

package/lib/core/dispatch-schema.mjs

@@ -0,0 +1,107 @@
+// lib/core/dispatch-schema.mjs — dispatch 工具的 output 结果 schema（closed oneOf），
+// 从 dispatch-tool.mjs 拆出的纯数据声明（拆出时同步新增 elapsedMs/stopReason 共享
+// 字段）。三个分支（background / continuable / foreground）共享同一套元数据键集
+// （判别键 kind/jobId/subagentId/output 除外），由 pure.mjs 的
+// assertResultSchemaConsistency 在 apply 时锁定——任一分支漏补共享字段即 throw。
+// 纯数据、零依赖。
+
+export const DISPATCH_OUTPUT_SCHEMA = {
+  // Observability metadata on every result. OneOf covers the
+  // background variant (kind/jobId) and the foreground variant (output),
+  // both closed and both carrying the effective delegation values.
+  // `ignored` must appear in ALL three branches (with the shared `preset`
+  // / `provider` / `model` / `reasoningEffort` / `profile`), keeping the
+  // closed oneOf consistent — assertResultSchemaConsistency(dispatchTool
+  // .output.schema) in apply() fires if any 分支 忘补该字段.
+  oneOf: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        kind: { type: 'string', required: true, const: 'background' },
+        jobId: { type: 'string', required: true },
+        profile: { type: 'string' },
+        preset: { type: 'string' },
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        reasoningEffort: { type: 'string' },
+        tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；后台结算经 job 结果携带，dispatch 结果不带。' },
+        childUsage: {
+          type: 'object',
+          additionalProperties: false,
+          description: '真实计费 token 五段分解（缓存读/写为可选）；后台结算经 job 结果携带，dispatch 结果不带。',
+          properties: {
+            inputTokens: { type: 'number' },
+            outputTokens: { type: 'number' },
+            cacheReadTokens: { type: 'number' },
+            cacheWriteTokens: { type: 'number' },
+            reasoningTokens: { type: 'number' }
+          }
+        },
+        elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；后台结算经 job 结果携带，dispatch 结果不带。' },
+        stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；后台结算经 job 结果携带，dispatch 结果不带。' },
+        ignored: { type: 'array', items: { type: 'string' } }
+      }
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        kind: { type: 'string', required: true, const: 'continuable' },
+        subagentId: { type: 'string', required: true },
+        profile: { type: 'string' },
+        preset: { type: 'string' },
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        reasoningEffort: { type: 'string' },
+        tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台/后台结算时携带，continuable 实际省略。' },
+        childUsage: {
+          type: 'object',
+          additionalProperties: false,
+          description: '真实计费 token 五段分解（缓存读/写为可选）；仅前台/后台 completed 结算时携带，continuable 实际省略。',
+          properties: {
+            inputTokens: { type: 'number' },
+            outputTokens: { type: 'number' },
+            cacheReadTokens: { type: 'number' },
+            cacheWriteTokens: { type: 'number' },
+            reasoningTokens: { type: 'number' }
+          }
+        },
+        elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；continuable 不结算，实际省略。' },
+        stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；continuable 不结算，实际省略。' },
+        ignored: { type: 'array', items: { type: 'string' } }
+      }
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        output: { type: 'string', required: true },
+        profile: { type: 'string' },
+        preset: { type: 'string' },
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        reasoningEffort: { type: 'string' },
+        tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台 completed 结算时携带。' },
+        childUsage: {
+          type: 'object',
+          additionalProperties: false,
+          description: '真实计费 token 五段分解（缓存读/写为可选）；前台 completed 结算时携带。',
+          properties: {
+            inputTokens: { type: 'number' },
+            outputTokens: { type: 'number' },
+            cacheReadTokens: { type: 'number' },
+            cacheWriteTokens: { type: 'number' },
+            reasoningTokens: { type: 'number' }
+          }
+        },
+        elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；前台 completed 结算时携带。' },
+        stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；前台 completed 结算时携带。' },
+        ignored: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  ]
+};