dsh-subagent-profile 0.2.0 → 0.3.0

package/lib/{pure.mjs → core/pure.mjs}

@@ -1,9 +1,8 @@
-// lib/pure.mjs — import-free pure helpers extracted from index.mjs (V2 T0-2).
-// These four have no @deepseek-ai imports and no external dependencies; each
-// function body is verbatim from index.mjs. @deepseek-ai symbols stay out of
-// this module — the readResult symbols converge in lib/shims.mjs, and index.mjs's
-// remaining direct @deepseek-ai imports converge there too after the V2.0-mid
-// 12-module split (target state).
+// lib/core/pure.mjs — import-free pure helpers (extracted from index.mjs and grown
+// by later refactors). No @deepseek-ai imports and no external dependencies:
+// @deepseek-ai symbols converge in lib/core/shims.mjs (the only such entry point),
+// and this module is safe to import from bare-CI tests without the junction
+// packages. Every function here is deterministic and free of service/fs access.
 
 // Shipped toStopReason: map a turn-end reason to the seam's terminal vocabulary.
 export function toStopReason(reason) {
@@ -43,7 +42,7 @@ export function textFrom(blocks) {
     .join('');
 }
 
-// --- V2 安全 P0-a：统一输入 schema（SPEC §7.2 / §12.1-12.2）-----------------
+// --- 统一输入 schema ----------------------------------------------------------
 // sanitizeProfile is the single per-profile sampler shared by loadProfiles
 // (strict=false, migration-tolerant) and the HTTP /add write path (strict=true,
 // write-reject). It normalizes each field with a field-specific sampler and
@@ -55,7 +54,7 @@ export function textFrom(blocks) {
 //                dedupe) do NOT produce a warning, so callers can treat a
 //                non-empty warnings list as "this write would drop data".
 
-// persona length cap. 建议值 2048，待实测（SPEC §7.2 / §13 回填清单）。The cap
+// persona length cap. 建议值 2048，待实测。The cap
 // applies to the INJECTED persona text, i.e. the guidance prefix + the raw text.
 export const PERSONA_MAX_CHARS = 2048;
 
@@ -64,15 +63,14 @@ export const PERSONA_MAX_CHARS = 2048;
 export const GUIDANCE_PREFIX = '[guidance, not authority] ';
 
 // Shared delegation caps — single source of truth for sanitizeProfile and the
-// cost guard in index.mjs (SPEC §7.3 keeps these hard caps always-on).
+// cost guard in lib/core/cost-guard.mjs (hard caps always-on).
 export const MAX_TOKENS = 65536;
 export const MAX_DEPTH = 3;
 
-// --- V2 安全 P0-b：cost guard 硬上限（SPEC §7.3）-------------------------------
-// assertHardLimits is the always-on budget-cap check. It was moved OUT of the
-// `llm`-dependency branch in index.mjs's assertCostGuard: maxTokens / maxDepth
-// are hard delegation caps, so they must NOT silently stop applying when the
-// `llm` service is absent (the old `if (llm === undefined) return` skipped them).
+// --- cost guard 硬上限 --------------------------------------------------------
+// assertHardLimits is the always-on budget-cap check, independent of the `llm`
+// service: maxTokens / maxDepth are hard delegation caps, so they must NOT
+// silently stop applying when the `llm` service is absent.
 // 超限 throw（中文、可操作），与 sanitizeProfile 共用同一组常量。非数字/未设值
 // 不触发（sanitizeProfile 已在写路径拒绝非数字，这里仅兜底运行时竞态）。
 export function assertHardLimits(maxTokens, maxDepth) {
@@ -84,13 +82,13 @@ export function assertHardLimits(maxTokens, maxDepth) {
   }
 }
 
-// --- V2 安全 P0-b：continuable 工具门闭集（SPEC §7.1）-------------------------
+// --- continuable 工具门闭集 ---------------------------------------------------
 // computeContinuableAllow pre-computes the CLOSED tool `allow` set for the
 // continuable dispatch path: 父工具集 − run_code − (toolFilter.deny)，并在存在
 // toolFilter.allow 时再 ∩ allow。空集 fail-loud（throw）—— 绝不静默派发零工具。
 //
-// 代码编辑者注意：这里写代码注释的「假设 / 失效条件」必须与 index.mjs
-// continuable 分支的注释保持一致（SPEC §7.1 要求写入代码注释与 README）。
+// 代码编辑者注意：这里写代码注释的「假设 / 失效条件」必须与 dispatch-tool.mjs
+// continuable 分支的注释保持一致（要求写入代码注释与 README）。
 export function computeContinuableAllow(parentNames, toolFilter = {}) {
   const parent = new Set(parentNames);
   parent.delete('run_code');
@@ -120,7 +118,86 @@ function sanitizeShortText(value) {
   return value.replace(/\r\n|\r|\n/g, ' ');
 }
 
-// --- V2 Token P0：结果回收默认剪枝（SPEC §8.2）-------------------------------
+// --- sanitizeProfile 各字段采样器（从 sanitizeProfile 拆出；行为逐字不变，
+// 共用 clean/warnings 两个累加对象）--------------------------------------------
+
+// name/description：null / '' 是「清除字段」哨兵（/add merge 层处理），原样透传
+// 不告警；其它非字符串（number/object/array）拒绝。
+function sanitizeTextField(key, value, clean, warnings) {
+  if (value === undefined) return;
+  if (value === null || value === '') { clean[key] = value; return; }
+  if (typeof value !== 'string') {
+    warnings.push({ field: key, reason: `${key} 必须为字符串` });
+    return;
+  }
+  clean[key] = sanitizeShortText(value);
+}
+
+// persona：计入引导前缀后的长度上限（strict 决定拒绝写入还是保留原值）。
+function sanitizePersonaField(value, clean, warnings, strict) {
+  if (value === undefined) return;
+  if (typeof value !== 'string') {
+    warnings.push({ field: 'persona', reason: 'persona 必须为字符串' });
+    return;
+  }
+  const wrappedLength = value.length === 0 ? 0 : GUIDANCE_PREFIX.length + value.length;
+  if (wrappedLength > PERSONA_MAX_CHARS) {
+    if (strict) {
+      warnings.push({
+        field: 'persona',
+        reason: `persona 超长：计入引导前缀 '${GUIDANCE_PREFIX.trim()}' 后 ${wrappedLength} 字符，超过上限 ${PERSONA_MAX_CHARS}，拒绝写入`,
+      });
+      return;
+    }
+    warnings.push({
+      field: 'persona',
+      reason: `persona 超长：计入引导前缀 '${GUIDANCE_PREFIX.trim()}' 后 ${wrappedLength} 字符，超过上限 ${PERSONA_MAX_CHARS}；保留原值（不截断），建议人工精简`,
+    });
+    clean.persona = value;
+    return;
+  }
+  clean.persona = value;
+}
+
+// maxTokens/maxDepth：有限数字 + 硬上限（MAX_TOKENS/MAX_DEPTH 由调用方注入）。
+function sanitizeNumericField(key, value, clean, warnings, max) {
+  if (value === undefined) return;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    warnings.push({ field: key, reason: `${key} 必须为有限数字` });
+    return;
+  }
+  if (value > max) {
+    warnings.push({ field: key, reason: `${key} ${value} 超过上限 ${max}` });
+    return;
+  }
+  clean[key] = value;
+}
+
+// toolFilter：allow/deny 去重、丢弃空字符串；非法子字段按字段粒度移除。未知键
+// 忽略；空（或全非法）的 toolFilter 直接不写入 clean（与 /add 写路径镜像）。
+function sanitizeToolFilterField(value, clean, warnings) {
+  if (value === undefined) return;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    warnings.push({ field: 'toolFilter', reason: 'toolFilter 必须为对象' });
+    return;
+  }
+  const tf = {};
+  for (const op of ['allow', 'deny']) {
+    const sub = value[op];
+    if (sub === undefined) continue;
+    if (!Array.isArray(sub) || !sub.every((s) => typeof s === 'string')) {
+      warnings.push({ field: `toolFilter.${op}`, reason: `toolFilter.${op} 必须为字符串数组` });
+      continue;
+    }
+    const deduped = [...new Set(sub.filter((s) => s.length > 0))];
+    if (deduped.length > 0) tf[op] = deduped;
+  }
+  // Unknown toolFilter keys are ignored; an empty (or fully-invalid)
+  // toolFilter is simply omitted from clean (mirrors the /add write path).
+  if (Object.keys(tf).length > 0) clean.toolFilter = tf;
+}
+
+// --- 结果回收默认剪枝 ----------------------------------------------------------
 // 子结果默认复用宿主 `toolResultPruner.pruneContent` 预剪（纯函数、零 LLM），
 // 在 `textFrom` 之前执行，把回灌进父上下文的体积压到阈值内。
 //
@@ -128,8 +205,8 @@ function sanitizeShortText(value) {
 // 现行 compaction-basic 的 4096/1024 更保守）。**待实测**——宿主
 // toolResultPruner.pruneContent(blocks) 只接收 blocks，自身读取其配置
 // （thresholdChars/headChars/tailChars），因此这三个常量当前**不会**作为实参
-// 传给宿主 pruner；它们记录本条目的子级口径，并保留给 V2.0-中期「信封 / 精修
-// 剪枝」路径使用。改动前先实测真实分布再回填 SPEC §13。
+// 传给宿主 pruner；它们记录本条目的子级口径，并保留给后续「信封 / 精修
+// 剪枝」路径使用。改动前先实测真实分布再校准。
 export const PRUNE_HEAD_CHARS = 2048;
 export const PRUNE_TAIL_CHARS = 1024;
 export const PRUNE_MIN_KEEP = 128;
@@ -139,8 +216,8 @@ export const PRUNE_MIN_KEEP = 128;
 //   - `pruner`   — the `toolResultPruner` service, or undefined.
 // Returns the (possibly pruned) blocks, or an empty array placeholder. When the
 // pruner is absent (headless deployment without the compaction pruner) OR the
-// content is not an array, it falls back to NO pruning — 剪枝是增强，绝非硬依赖
-// （SPEC §8.2）。A host pruner that throws on an unusual content shape also
+// content is not an array, it falls back to NO pruning — 剪枝是增强，绝非硬依赖。
+// A host pruner that throws on an unusual content shape also
 // falls back to the full output, because automatic pruning must NEVER swallow a
 // legitimate child result.
 export function pruneBlocks(blocks, pruner) {
@@ -155,9 +232,9 @@ export function pruneBlocks(blocks, pruner) {
   return Array.isArray(blocks) ? blocks : [];
 }
 
-// --- V2 Token P0：continuable 可见性修复（SPEC §8.4 / 共享规则 R1）-----------
-// R1 requires the three closed `output.schema.oneOf` branches
-// (background / continuable / foreground) to carry an IDENTICAL shared meta key
+// --- continuable 可见性修复 ----------------------------------------------------
+// 共享一致性规则：三个 closed `output.schema.oneOf` 分支
+// (background / continuable / foreground) must carry an IDENTICAL shared meta key
 // set whenever a result-meta field is added — so `ignored`, `reasoningEffort`,
 // `profile/preset/provider/model` must appear in ALL three branches, keeping the
 // model-side schema from rejecting a分支 that "forgot" the field.
@@ -165,7 +242,7 @@ export function pruneBlocks(blocks, pruner) {
 // 判据：元数据集合 = 每个分支 properties 的键集，**剔除**各分支自有的判别键
 // （`kind`/`jobId`/`subagentId`/`output`——background/continuable/foreground 各自
 // 的判别字段不同，不纳入一致性比较）。剩下必须是三者的公共元数据集合，三处
-// 逐一对齐；任一分支缺漏/多余公共元数据键即 throw（中文、指明 R1）。
+// 逐一对齐；任一分支缺漏/多余公共元数据键即 throw（中文、指明一致性规则）。
 const RESULT_SCHEMA_DISCRIMINATOR_KEYS = new Set(['kind', 'jobId', 'subagentId', 'output']);
 
 export function assertResultSchemaConsistency(schema) {
@@ -217,7 +294,7 @@ const KNOWN_PROFILE_FIELDS = new Set([
  * Non-rejection normalizations (description/name flatten, toolFilter dedupe) are
  * silent and never produce a warning.
  *
- * Security (P1): `clean` is `Object.create(null)` (no inherited `__proto__`
+ * Security: `clean` is `Object.create(null)` (no inherited `__proto__`
  * setter) and only whitelisted fields are copied, so a hostile `__proto__` /
  * `constructor` / `prototype` key is ignored rather than polluting the result.
  */
@@ -235,93 +312,21 @@ export function sanitizeProfile(profile, options = {}) {
     }
     switch (key) {
       case 'name':
-      case 'description': {
-        if (value === undefined) break;
-        // null / '' are the "clear this field" sentinels the /add merge layer
-        // handles; pass them through unchanged rather than flagging null as an
-        // illegal type. Any OTHER non-string (number / object / array) is
-        // rejected.
-        if (value === null || value === '') { clean[key] = value; break; }
-        if (typeof value !== 'string') {
-          warnings.push({ field: key, reason: `${key} 必须为字符串` });
-          break;
-        }
-        clean[key] = sanitizeShortText(value);
+      case 'description':
+        sanitizeTextField(key, value, clean, warnings);
         break;
-      }
-      case 'persona': {
-        if (value === undefined) break;
-        if (typeof value !== 'string') {
-          warnings.push({ field: 'persona', reason: 'persona 必须为字符串' });
-          break;
-        }
-        const wrappedLength = value.length === 0 ? 0 : GUIDANCE_PREFIX.length + value.length;
-        if (wrappedLength > PERSONA_MAX_CHARS) {
-          if (strict) {
-            warnings.push({
-              field: 'persona',
-              reason: `persona 超长：计入引导前缀 '${GUIDANCE_PREFIX.trim()}' 后 ${wrappedLength} 字符，超过上限 ${PERSONA_MAX_CHARS}，拒绝写入`,
-            });
-            break;
-          }
-          warnings.push({
-            field: 'persona',
-            reason: `persona 超长：计入引导前缀 '${GUIDANCE_PREFIX.trim()}' 后 ${wrappedLength} 字符，超过上限 ${PERSONA_MAX_CHARS}；保留原值（不截断），建议人工精简`,
-          });
-          clean[key] = value;
-          break;
-        }
-        clean[key] = value;
+      case 'persona':
+        sanitizePersonaField(value, clean, warnings, strict);
         break;
-      }
-      case 'maxTokens': {
-        if (value === undefined) break;
-        if (typeof value !== 'number' || !Number.isFinite(value)) {
-          warnings.push({ field: 'maxTokens', reason: 'maxTokens 必须为有限数字' });
-          break;
-        }
-        if (value > MAX_TOKENS) {
-          warnings.push({ field: 'maxTokens', reason: `maxTokens ${value} 超过上限 ${MAX_TOKENS}` });
-          break;
-        }
-        clean[key] = value;
+      case 'maxTokens':
+        sanitizeNumericField(key, value, clean, warnings, MAX_TOKENS);
         break;
-      }
-      case 'maxDepth': {
-        if (value === undefined) break;
-        if (typeof value !== 'number' || !Number.isFinite(value)) {
-          warnings.push({ field: 'maxDepth', reason: 'maxDepth 必须为有限数字' });
-          break;
-        }
-        if (value > MAX_DEPTH) {
-          warnings.push({ field: 'maxDepth', reason: `maxDepth ${value} 超过上限 ${MAX_DEPTH}` });
-          break;
-        }
-        clean[key] = value;
+      case 'maxDepth':
+        sanitizeNumericField(key, value, clean, warnings, MAX_DEPTH);
         break;
-      }
-      case 'toolFilter': {
-        if (value === undefined) break;
-        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-          warnings.push({ field: 'toolFilter', reason: 'toolFilter 必须为对象' });
-          break;
-        }
-        const tf = {};
-        for (const op of ['allow', 'deny']) {
-          const sub = value[op];
-          if (sub === undefined) continue;
-          if (!Array.isArray(sub) || !sub.every((s) => typeof s === 'string')) {
-            warnings.push({ field: `toolFilter.${op}`, reason: `toolFilter.${op} 必须为字符串数组` });
-            continue;
-          }
-          const deduped = [...new Set(sub.filter((s) => s.length > 0))];
-          if (deduped.length > 0) tf[op] = deduped;
-        }
-        // Unknown toolFilter keys are ignored; an empty (or fully-invalid)
-        // toolFilter is simply omitted from clean (mirrors the /add write path).
-        if (Object.keys(tf).length > 0) clean.toolFilter = tf;
+      case 'toolFilter':
+        sanitizeToolFilterField(value, clean, warnings);
         break;
-      }
       default:
         clean[key] = value;
         break;

package/lib/{shims.mjs → core/shims.mjs}

@@ -1,6 +1,6 @@
-// lib/shims.mjs — facade (V2 Task 6a). The ONLY module that imports the
+// lib/core/shims.mjs — facade. The ONLY module that imports the
 // @deepseek-ai symbols index.mjs relies on, converging the previously
-// top-level-scattered import surface (SPEC §9.2). Two failure classes:
+// top-level-scattered import surface. Two failure classes:
 //
 //   Guard-type (fail-loud, NO fallback): assertSubagentMaxDepth /
 //   resolveChildDepth are STATICALLY imported and re-exported. A rename/removal
@@ -23,14 +23,14 @@
 //   also verifies the value is a function before accepting it.
 
 import { randomUUID } from 'node:crypto';
-// Guard-type: static, fail-loud — no fallback (SPEC §9.2). Kept as the only two
+// Guard-type: static, fail-loud — no fallback. Kept as the only two
 // static @deepseek-ai imports; a missing export aborts module load with a clear
 // error BEFORE apply can run, which is the isolation this class exists for.
 import { assertSubagentMaxDepth, resolveChildDepth } from '@deepseek-ai/dsh-subagent';
 import { toStopReason } from './pure.mjs';
 
-// warn: at module top level there is no ctx / logger, so degrade to console.warn
-// (SPEC §9.2). The prefix keeps the source recognizable in a shared host log.
+// warn: at module top level there is no ctx / logger, so degrade to console.warn.
+// The prefix keeps the source recognizable in a shared host log.
 function warn(...parts) {
   console.warn('[dsh-subagent-profile]', ...parts);
 }
@@ -61,9 +61,9 @@ async function loadSoft(pkg, symbol, fallback, warnMessage, importer = DYNAMIC_I
 
 // --- local fallbacks (import-free, duck-typed, functionally equivalent) ----
 // Each is the minimal local reimplementation that preserves the observable
-// contract of the shipped helper. See the fallback-semantics report in the Task
-// 6a summary; these are exported via `__fallbacks` so tests can exercise the
-// degraded path even though the junction packages resolve successfully here.
+// contract of the shipped helper; these are exported via `__fallbacks` so tests
+// can exercise the degraded path even though the junction packages resolve
+// successfully here.
 
 // foldConsumedWork: **近似、非等价**——readResult 只读 `.end`（终止 turn/end 事件）来
 // 推导 stopReason。shipped fold 是精密的 stepped/claimed 状态机；本降级实现取最后一个
@@ -155,7 +155,7 @@ function resolveChildAgentOptionsFallback(parent, requested, childDepth) {
 // defineTool: the dispatch tool cannot exist without dsh-tools. Fail-loud at the
 // point of use with a clear, actionable message — the module still LOADS, and
 // calling this during apply surfaces the exact missing-dependency story instead
-// of a cryptic module-not-found at import time (SPEC §9.2 "不崩溃").
+// of a cryptic module-not-found at import time（加载不崩溃，调用点才报错）。
 function defineToolFallback() {
   throw new Error('dsh-tools 缺失：dispatch 工具不可用');
 }

package/lib/core/whitelist.mjs

@@ -0,0 +1,22 @@
+// lib/core/whitelist.mjs — target-preset whitelist derived from the runtime
+// roster, not hard-coded: system-trust presets when agentPresets exists, else
+// the shipped fallback names. Moved verbatim from index.mjs;
+// import-free (no @deepseek-ai dependency).
+//
+// Injection note: the original apply-closure version took `agentCtx` and read
+// `agentCtx.get('agentPresets')` itself. The caller now injects the service —
+// `resolveWhitelist(parent.ctx.get('agentPresets'))` — so the module does not
+// depend on apply-closure state. `parent.ctx.get('agentPresets')` yields the
+// exact same value (service or undefined), so the fallback semantics are
+// unchanged. FALLBACK_WHITELIST is exported for the tests.
+
+// The target-preset whitelist is derived from the runtime roster, not
+// hard-coded: system-trust presets when agentPresets exists, else the
+// shipped fallback names.
+export const FALLBACK_WHITELIST = ['standard', 'code', 'minimal'];
+
+export async function resolveWhitelist(agentPresets) {
+  if (agentPresets === undefined) return FALLBACK_WHITELIST;
+  const presets = await agentPresets.list();
+  return (presets ?? []).filter((preset) => preset && preset.trust === 'system').map((preset) => preset.id);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-profile",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Dispatch one-shot subtasks to derived subagents with per-task overrides (preset/model/provider/reasoningEffort/persona/tool whitelist), a runtime-derived cost guard, a subagent-profiles service, observability metadata, and a web-GUI settings page plus a dispatch tool-call card.",
   "repository": {
     "type": "git",
@@ -33,8 +33,8 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": ">=0.1.0-rc.6 <0.2.0",
-    "@deepseek-ai/dsh-subagent": ">=0.1.0-rc.6 <0.2.0",
     "@deepseek-ai/dsh-llm": ">=0.1.0-rc.6 <0.2.0",
+    "@deepseek-ai/dsh-subagent": ">=0.1.0-rc.6 <0.2.0",
     "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <0.2.0"
   },
   "peerDependenciesMeta": {
@@ -53,9 +53,11 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-subagent": "0.1.0-rc.8",
     "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-tools": "0.1.0-rc.8"
+    "@deepseek-ai/dsh-subagent": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.8",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.9.0"
   },
   "engines": {
     "node": "^22.19.0 || >=24"
@@ -73,6 +75,8 @@
   "license": "MIT",
   "scripts": {
     "release": "node scripts/release.mjs",
-    "test": "node --test \"test/**/*.test.mjs\""
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "test:bare": "node --test test/pure.test.mjs test/input-schema.test.mjs test/catalog-integrity.test.mjs",
+    "preflight": "node scripts/preflight.mjs"
   }
 }