dsh-subagent-profile 0.2.0 → 0.3.0

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/http-routes.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,108 @@
+// 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).
+// 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 存在但其 provider 目录为空（无发现能力）→ 无法核验。
+// 读取失败同样视为空目录（保守，随后走 allowFailOpen 门）。
+async function isLlmDirectoryEmpty(llm) {
+  try {
+    const providers = await llm.listProviders();
+    return (providers ?? []).length === 0;
+  } catch {
+    return true;
+  }
+}
+
+// ④ provider 注册校验（目录非空时才能判定「不在目录」）。
+async function assertProviderRegistered(llm, 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)) {
+    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".
+async function assertModelAdvertised(llm, profile, effectiveProvider) {
+  if (typeof profile.model !== 'string' || profile.model.length === 0) return;
+  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 });
+  }
+  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) {
+  // ① 硬上限 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 || await isLlmDirectoryEmpty(llm)) {
+    if (allowFailOpen === true) {
+      logger.warn('llm 不可用：fail-open 兼容模式（v1 数据迁移中，建议保存一次配置以升级到 fail-loud）');
+      return;
+    }
+    throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
+  }
+
+  // ④ provider 注册校验。
+  await assertProviderRegistered(llm, 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 assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel);
+}

package/lib/core/delegation.mjs

@@ -0,0 +1,61 @@
+// 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.
+export async function settleStart(start, signal, meta, prune = (blocks) => blocks) {
+  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: 'completed', output: textFrom(prune(result.output)), ...meta };
+  } catch (error) {
+    return signal.aborted ? { status: 'killed', ...meta } : { status: 'failed', detail: String(error), ...meta };
+  } 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-tool.mjs

@@ -0,0 +1,371 @@
+// lib/core/dispatch-tool.mjs — `dispatch` 工具（defineTool schema + execute）、
+// 结果 schema 一致性锁与 syncTool 注册/注销逻辑，从 index.mjs 逐字拆出。
+// 仅引用 lib + shims；无 @deepseek-ai 依赖（shims 是唯一入口）。
+//
+// Injection: every apply-closure / ctx dependency is an explicit parameter —
+//   register    ctx.tools.register (the tool is registered/unregistered by
+//               syncTool, so the settings switch can remove it at runtime),
+//   store       the profile store (resolveProfile for the base profile,
+//               getAllowFailOpen for the cost guard),
+//   getEnabled  reads the apply-closure `enabled` flag (continuable fail-loud
+//               gate + syncTool registration condition),
+//   getService  request-time service getter (ctx.get('toolResultPruner') /
+//               ctx.get('jobs') are read per call, never at apply time),
+//   logger      ctx.logger (decision-level dispatch log + continuable warns),
+//   subagents   ctx.subagents (start / startContinuable drive the child).
+// The factory returns { syncTool, dispose }: syncTool is handed to the HTTP
+// routes (/set-enabled), dispose runs on plugin teardown.
+//
+// execute 按预检段 + 前台/后台/continuable 三分支拆为模块级私有函数；
+// parameters/output 声明为纯数据，驻留模块级常量（与数据表同性质，不受函数
+// 行门约束）——工厂保持装配态，行为逐字不变。
+
+import { defineTool } from './shims.mjs';
+import { computeContinuableAllow, textFrom, stopReasonError, withPartialText, pruneBlocks, assertResultSchemaConsistency } from './pure.mjs';
+import { resolveWhitelist } from './whitelist.mjs';
+import { assertCostGuard } from './cost-guard.mjs';
+import { settleStart } from './delegation.mjs';
+
+// --- 工具声明纯数据（从工厂提到模块级；defineTool 只读不改）----------------------
+
+const DISPATCH_PARAMETERS = {
+  profile: { type: 'string', description: 'Optional profile id from the profile registry (built-ins: swap-standard, researcher, plus any you define in the settings page); omit to inherit the parent preset and tools as-is.' },
+  preset: { type: 'string', description: 'Explicit target preset override; must be a system-trust preset of this runtime.' },
+  model: { type: 'string', description: 'Explicit model override for the child.' },
+  provider: { type: 'string', description: 'Explicit provider override for the child.' },
+  reasoningEffort: { type: 'string', description: 'Explicit reasoning-effort override injected into every child request.' },
+  persona: { type: 'string', description: 'Persona text shadowing the child deployment:persona section.' },
+  toolFilter: {
+    type: 'object',
+    // DSL 对象参数默认拒绝未知键，toolFilter 必须闭合其 schema，
+    // 否则 defineTool 在 apply 时 throw、插件加载失败。
+    additionalProperties: false,
+    description: 'Extra tool whitelist intersection for the child (intersected with the parent tool set).',
+    properties: {
+      allow: { type: 'array', items: { type: 'string' }, description: 'When present, only these tool names are kept.' },
+      deny: { type: 'array', items: { type: 'string' }, description: 'These tool names are always removed.' }
+    }
+  },
+  maxTokens: { type: 'number', description: 'Explicit max-tokens budget for the child.' },
+  maxDepth: { type: 'number', description: 'Absolute delegation-depth cap for this child.' },
+  run_in_background: { type: 'boolean', description: '异步 one-shot：走 jobs.start 包 start()，返回 jobId；仍单轮即弃，非 continuable' },
+  continuable: { type: 'boolean', description: 'Start a durable continuable subagent instead of a one-shot: returns a subagentId immediately and keeps the child conversation available for later turns via the send_message tool. Defaults to false.' },
+  // 信封模式 = opt-in（仅「中段即交付物」的任务用）。当前**仅预留**：工具
+  // schema 暴露此参数作字段契约，execute 不消费它（结构化信封回收尚未启用）。
+  // 见 execute 内注释。
+  envelope: { type: 'boolean', description: '预留：结构化信封回收（V2.0 中期启用，当前不生效）' },
+  prompt: { type: 'string', required: true, description: 'The complete, self-contained task for the child (it does not see this conversation).' }
+};
+
+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' },
+        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' },
+        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' },
+        ignored: { type: 'array', items: { type: 'string' } }
+      }
+    }
+  ]
+};
+
+// continuable 丢弃 preset 换用与 reasoningEffort —— 渲染行把 `ignored`
+// 列表回显出来（`reasoningEffort=<值>(ignored)`，再加 ignored 项明细），让模型
+// 「看见」被丢弃项；background/foreground 无忽略项时该后缀为空。
+const DISPATCH_RENDER = (_args, value) => {
+  const ignored = value.ignored !== undefined && value.ignored.length > 0
+    ? `(ignored: ${value.ignored.join(', ')})`
+    : '';
+  const text = value.kind === 'background'
+    ? `[dispatch] background job ${value.jobId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}`
+    : value.kind === 'continuable'
+      ? `[dispatch] started subagent ${value.subagentId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}`
+      : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}\n\n${value.output}`;
+  return [{ type: 'text', text }];
+};
+
+// --- execute 预检段（从 execute 拆出；行为逐字不变）-----------------------------
+
+// Resolve the base profile (side channel), then overlay explicit args.
+function mergeProfileArgs(args, store) {
+  const base = args.profile !== undefined ? store.resolveProfile(args.profile) : {};
+  const merged = { ...base };
+  for (const key of ['preset', 'model', 'provider', 'reasoningEffort', 'persona', 'toolFilter', 'maxTokens', 'maxDepth']) {
+    if (args[key] !== undefined) merged[key] = args[key];
+  }
+  return merged;
+}
+
+// Pre-check: explicit concrete preset must be in the runtime-derived whitelist;
+// a preset equal to the parent's composed preset is rewritten to
+// 'inherit' (no swap).
+async function assertPresetWhitelist(parent, merged) {
+  if (typeof merged.preset !== 'string' || merged.preset === 'inherit') return;
+  const whitelist = new Set(await resolveWhitelist(parent.ctx.get('agentPresets')));
+  if (!whitelist.has(merged.preset)) {
+    throw new Error(`dispatch: preset "${merged.preset}" is not in the target-preset whitelist`);
+  }
+  const parentPresets = parent.ctx.get('agentPresets');
+  const parentComposed = parentPresets !== undefined ? parentPresets.composedPreset(parent.ctx) : undefined;
+  if (merged.preset === parentComposed) merged.preset = 'inherit';
+}
+
+// Effective delegation values for observability.
+function buildMeta(args, merged, parent) {
+  return {
+    profile: args.profile ?? '(inline)',
+    preset: merged.preset ?? 'inherit',
+    provider: merged.provider ?? parent.options.provider ?? '(parent)',
+    model: merged.model ?? parent.options.model ?? '(parent)',
+    reasoningEffort: merged.reasoningEffort ?? '(default)'
+  };
+}
+
+// Assemble the foreground/background request (continuable builds its own below).
+function buildRequest(args, merged, parent, signal) {
+  return {
+    label: String(args.prompt ?? '').slice(0, 60),
+    prompt: [{ type: 'text', text: args.prompt }],
+    parent,
+    signal,
+    profile: merged,
+    ...(merged.persona !== undefined ? { persona: merged.persona } : {}),
+    ...(merged.toolFilter !== undefined ? { toolFilter: merged.toolFilter } : {}),
+    ...(merged.maxDepth !== undefined ? { maxDepth: merged.maxDepth } : {})
+  };
+}
+
+// Decision-level log: resolved effective delegation inputs, after the cost
+// guard and after request assembly, before dispatch.
+function logDispatchDecision(logger, args, merged, parent) {
+  logger.info('[dsh-subagent-profile] dispatch:', JSON.stringify({
+    profile: args.profile ?? '(inline)',
+    preset: merged.preset ?? 'inherit',
+    provider: merged.provider ?? parent.options.provider ?? '(parent)',
+    model: merged.model ?? parent.options.model ?? '(parent)',
+    reasoningEffort: merged.reasoningEffort ?? '(default)',
+    maxDepth: merged.maxDepth ?? null,
+    background: args.run_in_background === true,
+    continuable: args.continuable === true
+  }));
+}
+
+// --- continuable 分支（从 execute 拆出）------------------------------------------
+
+// 预加工 toolFilter 为闭集 allow（父工具集 − run_code − deny）：continuable
+// 走宿主 applyChildComposition→tools.restrict，prepareContinuable 返回 {}，
+// 插件侧无法重算父∩子交集，故在此把 allow 预加工为闭集传到 request。
+// 假设：continuable 继承父预设（preset swap 被忽略）⇒ 子工具集 ≈ 父工具集；
+// 失效条件：任何导致子工具集与父工具集不一致的宿主行为变化，父集都可能含
+// 子集上不存在之工具 → tools.restrict 抛「未知工具」→ 本缓解自动降级为
+// fail-loud（保守安全）。
+function buildContinuableRequest(args, merged, parent) {
+  const parentNames = new Set(parent.ctx.tools.schemas(parent).map((schema) => schema.name));
+  const effectiveAllow = computeContinuableAllow(parentNames, merged.toolFilter);
+  const hasAgentOptions = merged.provider !== undefined || merged.model !== undefined || merged.maxTokens !== undefined;
+  return {
+    prompt: [{ type: 'text', text: args.prompt }],
+    parent,
+    ...(hasAgentOptions ? { agentOptions: {
+      ...(merged.provider !== undefined ? { provider: merged.provider } : {}),
+      ...(merged.model !== undefined ? { model: merged.model } : {}),
+      ...(merged.maxTokens !== undefined ? { maxTokens: merged.maxTokens } : {})
+    } } : {}),
+    ...(merged.persona !== undefined ? { persona: merged.persona } : {}),
+    // 恒传闭集 allow（覆盖原 merged.toolFilter 透传）；空集在
+    // computeContinuableAllow 内 fail-loud。
+    toolFilter: { allow: effectiveAllow },
+    ...(merged.maxDepth !== undefined ? { maxDepth: merged.maxDepth } : {})
+  };
+}
+
+// Continuable (durable) path — startContinuable publishes a persistent child
+// and returns its durable id; the official send_message tool drives later
+// turns. Treated first so a caller asking for both background and continuable
+// gets the continuable child.
+async function runContinuable(args, merged, meta, parent, exec, deps) {
+  // provider `start` 的 !enabled 检查只拦
+  // `start`，不拦 `startContinuable` —— 这里显式补上。当前 syncTool 会在
+  // 禁用时注销 dispatch 工具（间接门），此处是防御性兜底：禁用后
+  // dispatch(continuable:true) 必须 fail-loud，不得静默派生子树。
+  if (!deps.getEnabled()) {
+    throw new Error('dispatch: 插件已禁用（设置 → 子 Agent 方案 重新启用）');
+  }
+  if (args.run_in_background === true) {
+    deps.logger.warn('[dsh-subagent-profile] dispatch: both continuable and run_in_background are true; continuable takes precedence');
+  }
+  // 已知降级：continuable 标准路径不支持 preset swap 和 reasoningEffort（subagent 包的 SubagentStartRequest 无 preset 字段、AgentOptions 无 reasoningEffort 字段）
+  if (merged.preset !== undefined && merged.preset !== 'inherit') {
+    deps.logger.warn(`[dsh-subagent-profile] continuable mode cannot swap preset; ignoring "${merged.preset}" (child inherits the parent preset)`);
+  }
+  if (merged.reasoningEffort !== undefined) {
+    deps.logger.warn(`[dsh-subagent-profile] continuable mode cannot set reasoningEffort; ignoring "${merged.reasoningEffort}"`);
+  }
+  const continuableRequest = buildContinuableRequest(args, merged, parent);
+  const { childId } = await deps.subagents.startContinuable({
+    provider: 'profile',
+    label: String(args.prompt ?? '').slice(0, 60),
+    request: continuableRequest,
+    signal: exec.signal
+  });
+  // Continuable drops the profile's preset swap and reasoningEffort (the child
+  // inherits the parent preset), so the observability meta must report what
+  // actually took effect, not the requested-but-ignored values.
+  // 可见性修复：`reasoningEffort` 回显**请求值**（经 meta.reasoningEffort），
+  // `preset:'inherit'` 是真实生效值；`ignored` 明确列出被丢弃项。
+  return {
+    kind: 'continuable',
+    subagentId: childId,
+    profile: meta.profile,
+    preset: 'inherit',
+    provider: meta.provider,
+    model: meta.model,
+    reasoningEffort: meta.reasoningEffort,
+    ignored: ['preset', 'reasoningEffort']
+  };
+}
+
+// --- 后台 / 前台分支（从 execute 拆出）--------------------------------------------
+
+// Background one-shot (job) path — jobs.start wraps start() with a native
+// AbortController (a Node global in a bundle; the dynamic-plugin sandbox needed
+// the hand-rolled shim instead); still one turn, not continuable.
+async function runBackground(args, meta, request, parent, deps, pruneResultOutput) {
+  const jobs = deps.getService('jobs');
+  if (jobs === undefined) {
+    throw new Error('dispatch: background jobs unavailable (load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs)');
+  }
+  const jobId = jobs.start({
+    kind: 'subagent',
+    label: String(args.prompt ?? '').slice(0, 60),
+    owner: parent,
+    run: () => {
+      const controller = new AbortController();
+      return {
+        cancel: (reason) => controller.abort(reason ?? 'dispatch: background subagent task killed'),
+        done: settleStart(deps.subagents.start('profile', { ...request, signal: controller.signal }), controller.signal, meta, pruneResultOutput)
+      };
+    }
+  });
+  return { kind: 'background', jobId, ...meta };
+}
+
+// Foreground: collect, always release the handle (dispose even when
+// run.result rejects), then fail loud on a non-completed stop reason.
+async function runForeground(meta, request, parent, deps, pruneResultOutput) {
+  const run = await deps.subagents.start('profile', request);
+  let result;
+  try {
+    result = await run.result;
+  } finally {
+    await run.dispose().catch(() => {});
+  }
+  // A non-'completed' stop reason is a failure; attach the child's
+  // partial output text (withPartialText style).
+  const failure = stopReasonError(result);
+  if (failure !== undefined) throw new Error(withPartialText(failure, result.output));
+  return { output: textFrom(pruneResultOutput(result.output)), ...meta };
+}
+
+// execute 主体：预检段 + 三分支分派，行为逐字不变。
+async function runDispatch(args, exec, deps) {
+  const parent = exec.agent;
+  if (!parent) throw new Error('dispatch requires calling agent');
+  const merged = mergeProfileArgs(args, deps.store);
+  await assertPresetWhitelist(parent, merged);
+  // Cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控）。
+  await assertCostGuard(parent, merged, deps.store.getAllowFailOpen(), deps.logger);
+  const meta = buildMeta(args, merged, parent);
+  const request = buildRequest(args, merged, parent, exec.signal);
+  // 结果回收默认剪枝：在 textFrom(result.output) 之前复用宿主
+  // toolResultPruner.pruneContent 预剪。`pruneResultOutput` 每次现取
+  // ctx.get('toolResultPruner') 以反映服务就绪状态；pruner 缺失时
+  // pruneBlocks 回退为不剪（剪枝是增强、非硬依赖）。envelope 参数虽已在
+  // 工具 schema 暴露（预留），但 execute **不消费**它。
+  const pruneResultOutput = (blocks) => pruneBlocks(blocks, deps.getService('toolResultPruner'));
+  logDispatchDecision(deps.logger, args, merged, parent);
+  if (args.continuable === true) return runContinuable(args, merged, meta, parent, exec, deps);
+  if (args.run_in_background === true) return runBackground(args, meta, request, parent, deps, pruneResultOutput);
+  return runForeground(meta, request, parent, deps, pruneResultOutput);
+}
+
+export function createDispatchTool({ register, store, getEnabled, getService, logger, subagents }) {
+  const deps = { store, getEnabled, getService, logger, subagents };
+  const dispatchTool = defineTool({
+    name: 'dispatch',
+    description: 'Dispatch a subtask to a derived subagent, optionally overriding its preset, model, provider, reasoning effort, persona, tool whitelist, token budget, or recursion depth. Foreground waits for the result; run_in_background: true starts a background job (single turn); continuable: true starts a durable subagent whose conversation stays available for later turns via the send_message tool. 前瞻：continuable 模式忽略 preset 换用与 reasoningEffort（结果以 ignored 提示）。',
+    parameters: DISPATCH_PARAMETERS,
+    output: { schema: DISPATCH_OUTPUT_SCHEMA, render: DISPATCH_RENDER },
+    isConcurrencySafe: () => true,
+    execute: (args, exec) => runDispatch(args, exec, deps),
+  });
+  // 共享一致性规则 lock: the closed oneOf result schema must carry an identical
+  // shared meta key set across all three branches. Fires only at apply time; a
+  // future meta-field add that forgets one 分支 throws here (once), so the
+  // model-side schema never silently rejects a分支.
+  assertResultSchemaConsistency(dispatchTool.output.schema);
+  // Register the tool only while enabled; unregister it the moment the switch
+  // turns off so it disappears from the model's tool list without a restart.
+  let disposeTool;
+  function syncTool() {
+    if (getEnabled() && disposeTool === undefined) {
+      disposeTool = register(dispatchTool);
+    } else if (!getEnabled() && disposeTool !== undefined) {
+      const dispose = disposeTool;
+      disposeTool = undefined;
+      dispose();
+    }
+  }
+  syncTool();
+  return {
+    syncTool,
+    dispose() {
+      if (disposeTool !== undefined) {
+        const dispose = disposeTool;
+        disposeTool = undefined;
+        dispose();
+      }
+    }
+  };
+}