dsh-subagent-profile 0.2.0 → 0.3.1

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

@@ -0,0 +1,83 @@
+// 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/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
+// picker. Tools absent here fall back to their raw name.
+export const TOOL_ZH = {
+  'bash': '终端命令',
+  'pwsh': 'PowerShell 命令',
+  'read': '读取文件',
+  'write': '写入文件',
+  'edit': '编辑文件',
+  'grep': '搜索文件内容',
+  'glob': '查找文件',
+  'web_search': '网页搜索',
+  'browser_navigate': '浏览器打开网址',
+  'browser_snapshot': '浏览器页面快照',
+  'browser_click': '浏览器点击',
+  'browser_type': '浏览器输入',
+  'browser_scroll': '浏览器滚动',
+  'browser_back': '浏览器后退',
+  'browser_forward': '浏览器前进',
+  'browser_press': '浏览器按键',
+  'browser_reload': '浏览器刷新',
+  'browser_wait': '浏览器等待',
+  'browser_get_text': '读取页面文本',
+  'dispatch': '派发子 Agent',
+  'subagent': '派生子 Agent',
+  'subagent_fork': '派生子 Agent（继承上下文）',
+  'send_message': '给子 Agent 发消息',
+  'interrupt_agent': '中断子 Agent',
+  'list_agents': '列出子 Agent',
+  'todo_write': '任务清单',
+  'create_goal': '创建目标',
+  'get_goal': '查看目标',
+  'update_goal': '更新目标',
+  'workflow': '编排多 Agent 工作流',
+  'ralph': 'Ralph 迭代',
+  'ask_user_question': '询问用户',
+  'skill': '加载技能',
+  'describe_image': '描述图片',
+  'read_image': '读取图片',
+  'modlens_read_image': '读取图片（modlens）',
+  'ssh_list': '列出 SSH 主机',
+  'ssh_exec': 'SSH 执行命令',
+  'ssh_upload': 'SSH 上传',
+  'ssh_download': 'SSH 下载',
+  'ssh_tunnel': 'SSH 隧道',
+  'ssh_cluster': 'SSH 集群执行',
+  'exit_plan_mode': '退出计划模式',
+  'incident_resolved': '标记事故已解决',
+  'dsh_rollback': '回滚 DSH',
+  'dsh_snapshot': 'DSH 快照',
+  'job_list': '列出后台任务',
+  'job_output': '读取后台任务输出',
+  'job_kill': '终止后台任务',
+  'str_replace_editor': '文本编辑',
+  'cordis_inspect_list': '列出 Cordis 服务',
+  'cordis_inspect_query': '查询 Cordis 服务',
+  'cordis_inspect_self': '查看自身 Cordis 服务',
+  'cordis_define': '定义 Cordis 服务',
+  'cordis_run': '运行 Cordis 服务',
+  'cordis_stop': '停止 Cordis 服务',
+  'cordis_undefine': '取消定义 Cordis 服务',
+  'run_code': '运行代码',
+};
+
+// Tool-name → 功能分类 map，覆盖 DSH 官方核心工具（固定集合）。插件工具
+// 走前缀提取（见 categoryOf），自建预设用 preset 名。
+export const TOOL_CATEGORY = {
+  'read': '文件', 'write': '文件', 'edit': '文件', 'grep': '文件', 'glob': '文件', 'str_replace_editor': '文件',
+  'bash': '终端', 'pwsh': '终端',
+  'web_search': '网络',
+  'todo_write': '任务', 'create_goal': '任务', 'get_goal': '任务', 'update_goal': '任务',
+  'subagent': '子 Agent', 'subagent_fork': '子 Agent', 'send_message': '子 Agent', 'interrupt_agent': '子 Agent', 'list_agents': '子 Agent',
+  'workflow': '工作流', 'ralph': '工作流',
+  'ask_user_question': '交互', 'skill': '交互',
+  'read_image': '图片', 'describe_image': '图片',
+  'cordis_inspect_list': 'Cordis', 'cordis_inspect_query': 'Cordis', 'cordis_inspect_self': 'Cordis',
+  'cordis_define': 'Cordis', 'cordis_run': 'Cordis', 'cordis_stop': 'Cordis', 'cordis_undefine': 'Cordis',
+  'exit_plan_mode': '计划',
+};

package/lib/core/cost-guard.mjs

@@ -0,0 +1,122 @@
+// 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
+//      they must NOT stop applying when `llm` is absent（历史教训：早期版本在
+//      llm 缺失时直接 return，连带跳过了硬上限，属缺陷——硬上限永远前置）。
+//   ② llm capability — validates provider / model / reasoningEffort against the
+//      live provider directory. When the `llm` service is absent OR its provider
+//      directory is empty (an adapter without discovery), capability cannot be
+//      verified: per `allowFailOpen`（迁移开关）either
+//      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';
+
+// ② 仅当 profile 请求了需核验能力面的字段时才进入 llm 校验（无头/headless 部署下
+// persona-only / toolFilter-only 的 profile 合法，不应被 fail-loud 拒绝）。
+function needsLlmCheck(profile) {
+  return ['provider', 'model', 'reasoningEffort'].some(
+    (key) => typeof profile[key] === 'string' && profile[key].length > 0
+  );
+}
+
+// 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 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
+function assertProviderRegistered(dir, profile) {
+  if (typeof profile.provider !== 'string' || profile.provider.length === 0) return;
+  if (!(dir.providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
+    throw new Error(`dispatch: provider "${profile.provider}" is not a registered provider`);
+  }
+}
+
+// ⑤ model 校验。resolveModelInfo does not reject unknown models (catalog
+//    membership is advisory), so validate against the advertised catalog
+//    instead. An EMPTY catalog (adapter without discovery) cannot be verified
+//    and is skipped — 目录级空集已在 ③ 走 allowFailOpen 分支，此处仅兜底
+//    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".
+//    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;
+  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));
+  if (listed.length > 0 && !known) {
+    throw new Error(`dispatch: model "${profile.model}" is not advertised by provider "${String(effectiveProvider)}"`);
+  }
+}
+
+// ⑥ reasoningEffort 校验。
+async function assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel) {
+  if (typeof profile.reasoningEffort !== 'string' || profile.reasoningEffort.length === 0) return;
+  try {
+    await llm.resolveCallConfig({ provider: effectiveProvider, model: effectiveModel, reasoningEffort: profile.reasoningEffort });
+  } catch (error) {
+    throw new Error(`dispatch: reasoningEffort "${profile.reasoningEffort}" is not supported by provider "${String(effectiveProvider)}" model "${String(effectiveModel)}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog) {
+  // ① 硬上限 always-on（不依赖 llm）。
+  assertHardLimits(profile.maxTokens, profile.maxDepth);
+
+  // ② 无 llm 能力面字段 → 无可核验，直接通过（headless 部署合法）。
+  if (!needsLlmCheck(profile)) return;
+
+  const llm = parent.ctx.get('llm');
+  // ③ 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 注册校验。
+  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, dir.modelsByProvider);
+  await assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel);
+}

package/lib/core/delegation.mjs

@@ -0,0 +1,81 @@
+// 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
+// foreground result closure in lib/core/profile-provider.mjs); no @deepseek-ai
+// dependency.
+
+import { stopReasonError, withPartialText, textFrom } from './pure.mjs';
+
+// 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
+// attached; hard failures never reject the job.
+// `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. `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,
+        elapsedMs: Date.now() - t0,
+        stopReason: result.stopReason
+      };
+    }
+    // 仅 completed 结算时测量（非 completed 走上方失败分支，不测）；在 dispose
+    // 之前读子 session。measureChild 缺失/失败返回 undefined → 省略字段（fail-soft）。
+    const childTotalTokens = measureChild(run.localAgent?.session);
+    const metaOut = {
+      ...meta,
+      ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+      elapsedMs: Date.now() - t0,
+      stopReason: 'completed'
+    };
+    return { status: 'completed', output: textFrom(prune(result.output)), ...metaOut };
+  } catch (error) {
+    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
+    // try/finally).
+    if (run !== undefined) await run.dispose().catch(() => {});
+  }
+}
+
+// Verbatim from the shipped SUBAGENT_DELEGATION_CONTEXT.
+export const DELEGATION_CONTEXT = 'You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it.';
+
+// Provider start 内 CUSTOM childSessionMeta 对象的纯组装，从 provider start
+// 抽出的可安全移动部分。取值侧仍留在 provider start（调用方
+// 注入）：cwd / parentSession 取自 parent.session.header，parentComposed /
+// swapPreset 由 agentPresets.composedPreset 与 profile.preset 算出，childDepth
+// 来自 resolveChildDepth。hasPresets=false（rosterless）时 agentPreset 整个省略
+// （非 rosterless 才记录——语义与原始内联对象逐字一致）。
+export function buildDispatchMeta({ cwd, hasPresets, swapPreset, preset, parentComposed, parentSession, childDepth }) {
+  return {
+    ...(cwd !== undefined ? { cwd } : {}),
+    ...(hasPresets
+      ? swapPreset
+        ? { agentPreset: preset }
+        : parentComposed !== undefined
+          ? { agentPreset: parentComposed }
+          : {}
+      : {}),
+    parentSession,
+    origin: 'subagent',
+    delegationDepth: childDepth
+  };
+}

package/lib/core/dispatch-schema.mjs

@@ -0,0 +1,71 @@
+// 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 结果不带。' },
+        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 实际省略。' },
+        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 结算时携带。' },
+        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' } }
+      }
+    }
+  ]
+};