dsh-agentic-tool-catalog 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.3.2 — 2026-11-12
+
+Fix: background catalog generation failed 100% on DSH **0.2.2-rc.2** with
+`AGENT_FAILED: Cannot read properties of undefined (reading 'id')`, plus hardening so the next
+host API move degrades gracefully instead of failing silently.
+
+- **Cause**: rc.2 flattened the `ctx.subagents.startActivation()` spec
+  (`SubagentActivationSpec`). `parent`, `prompt`, `maxDepth`, and `outputSchema` moved from
+  `spec.request.*` to the top level; `startActivation` now reads `spec.parent.id` directly.
+  0.3.1 still passed the 0.2.2-rc.1 nested shape, so `spec.parent` was `undefined` and every
+  generation threw before a child session was created. This was a host breaking change, not a
+  Computer Use plugin issue: an isolated DSH 0.2.2-rc.2 instance with only this plugin reproduced it.
+- **Compatibility adapter**: all version-shape knowledge now lives in `lib/subagent-compat.js`.
+  It sends the union of both shapes: request fields at the top level (0.2.2-rc.2+) and a
+  **non-enumerable** `request` property (0.2.1-rc.2 … 0.2.2-rc.1). Non-enumerability keeps rc.2's
+  external-provider rest-spread from forwarding the legacy nested object, while old versions still
+  read `spec.request`. Both host implementations ignore unknown keys, so one call supports both.
+- **Soft gate**: three consecutive shape rejections report `UNSUPPORTED_HOST`, pause automatic
+  generation for one hour, and keep the last-known-good catalog with an explicit
+  `catalog-generation-paused` warning instead of a stream of `AGENT_FAILED` retries. A plugin
+  reload clears the pause and the per-fingerprint backoff, so a fix takes effect immediately.
+- **Compatibility declaration**: `engines.dsh` is now the tested line `>=0.2.1-rc.2 <0.3.0-0`
+  instead of an open-ended range. `generation.activationShapes` reports `["flat","nested"]`.
+- **Tests**: `lib/subagent-compat.js` has a dedicated `scripts/verify-subagent-compat.mjs` that
+  drives the **real** `@deepseek-ai/dsh-subagent` `0.2.2-rc.1` and `0.2.2-rc.2`
+  `SubagentRuntime.startActivation` implementations: both accept the adapter spec, each reads its
+  own shape, a flat-only spec fails on rc.1, a nested-only spec fails on rc.2, and both versions
+  enforce the `outputSchema` capability. It runs as part of `npm test` (first run installs the two
+  pinned host packages into `reference/tmp/subagent-compat/`, gitignored).
+
 ## 0.3.1 — 2026-11-11
 
 Documentation-only release: the plugin page was rewritten around the user's questions (what it

package/README.md

@@ -98,7 +98,8 @@ dsh plugin --profile web add /path/to/dsh-agentic-tool-catalog
 dsh plugin add /path/to/dsh-agentic-tool-catalog
 ```
 
-Published package: `dsh-agentic-tool-catalog` (npm). Requires DSH `0.2.2-rc.1` or later.
+Published package: `dsh-agentic-tool-catalog` (npm). Requires DSH `>=0.2.1-rc.2 <0.3.0`;
+tested with `0.2.2-rc.1` and `0.2.2-rc.2` (both subagent activation shapes are supported).
 
 ```bash
 dsh plugin --profile web add dsh-agentic-tool-catalog
@@ -131,6 +132,11 @@ official ContextMeter: a segmented bar plus three rows (always available / loade
 freshness word, and one meta line (groups · storage · updated). There is no directory dump, no configuration, and
 no long explanatory copy. It uses official slots/theme tokens and follows the light/dark theme.
 
+## Development & release
+
+See [`docs/development.md`](docs/development.md) for the layered validation flow (link dev profile →
+npm artifact → staging composition → `next` dogfood → `latest`).
+
 ## Verification
 
 ```bash

package/README.zh.md

@@ -85,7 +85,8 @@ dsh plugin --profile web add /path/to/dsh-agentic-tool-catalog
 dsh plugin add /path/to/dsh-agentic-tool-catalog
 ```
 
-发布包：`dsh-agentic-tool-catalog`（npm）；要求 DSH `0.2.2-rc.1` 及以上。
+发布包：`dsh-agentic-tool-catalog`（npm）；要求 DSH `>=0.2.1-rc.2 <0.3.0`，
+已在 `0.2.2-rc.1` 与 `0.2.2-rc.2` 上验证（两种子代理激活 spec 形状都支持）。
 
 ## 性能（A/B：用 vs 不用）
 

package/docs/benchmark.md

@@ -50,5 +50,5 @@ Notes:
   `workspace-calendar-count` is excluded from the main table because it depends on MCP availability.
 - First-request token figures come from real session usage (`inputTokens + cacheReadTokens`); schema chars are a
   payload-size metric, **not** a chars/4 token estimate.
-- Full methodology and raw results: `benchmark/discovery/data-card.md` and `benchmark/discovery/results/` in the
+- Full methodology and raw results: `benchmark/data-card.md` and `benchmark/results/` in the
   source repository.

package/docs/data-card.md

@@ -86,7 +86,7 @@
   本卡使用的是工具面一致的 10–4x 批次；
 - 首请求 tokens 来自会话日志真实 usage（非 chars/4 估算）；schema 字符是载荷指标。成本/墙钟受模型与网络影响，应看多轮重复；
 - 复现：`node benchmark/discovery/card.mjs --baseline baseline-resident --treatment agent-catalog --tasks host-ops-session-list,docs-workers-limit,terminal-echo,goal-set,docs-d1-storage --markdown`
-  原始结果在 [`results/`](results/)，方法说明 [`benchmark/discovery/README.md`](README.md)。
+  原始结果在 [`results/`](../benchmark/results/)，方法说明 [`benchmark/README.md`](../benchmark/README.md)。
 
 ## 7. 和竞品怎么比
 

package/docs/detail.md

@@ -24,7 +24,7 @@ plugin. The catalog saves context, not by making tasks cheaper to run.
 
 ## Good to know
 
-- Works with DSH `>=0.2.1-rc.2` or `>=0.2.2-rc.1`.
+- Works with DSH `>=0.2.1-rc.2 <0.3.0`; tested on `0.2.2-rc.1` and `0.2.2-rc.2`.
 - v1 covers **tools**; native skills keep their normal behavior.
 - The catalog is derived data and contains no messages, prompts, tool results or credentials.
 - It does **not** regenerate on a timer: only when the set of available tools changes. One-time

package/docs/detail.zh.md

@@ -22,7 +22,7 @@ DSH 默认会把每个可见工具的完整 schema 放进每一次请求。这
 
 ## 你需要知道
 
-- 适用于 DSH `>=0.2.1-rc.2` 或 `>=0.2.2-rc.1`。
+- 适用于 DSH `>=0.2.1-rc.2 <0.3.0`；已在 `0.2.2-rc.1` 与 `0.2.2-rc.2` 上验证。
 - v1 覆盖 **tools**；DSH 原生 skills 行为不变。
 - 目录是派生数据，不含消息、提示词、工具结果或凭据。
 - **不会定时重新生成**：只有可用工具集发生变化时才重建。生成结果会被缓存，工具集稳定的情况下

package/lib/generation.js

@@ -14,6 +14,12 @@
  * @module @local/dsh-agentic-tool-catalog/generation
  */
 import { normalizeGroupId, summarizeGroups } from './catalog.js'
+import { ACTIVATION_SHAPES, isActivationShapeError, startSubagentActivation } from './subagent-compat.js'
+
+/** 连续多少次"宿主不认 activation spec"后暂停自动生成（避免 9/9 静默刷失败）。 */
+export const SHAPE_FAILURE_PAUSE_THRESHOLD = 3
+/** 形状不兼容暂停时长：1 小时；期间继续用 last-known-good 目录。 */
+export const SHAPE_FAILURE_PAUSE_MS = 60 * 60 * 1000
 
 export const AGENT_GROUP_DEFAULTS = {
   provider: 'spawn',
@@ -228,6 +234,8 @@ export function createAgentGrouper(ctx, config, logger, sharedStats = undefined)
   delete stats.fallbacks
   const provider = config?.catalogProvider ?? AGENT_GROUP_DEFAULTS.provider
   const timeoutMs = config?.catalogTimeoutMs ?? AGENT_GROUP_DEFAULTS.timeoutMs
+  /** 连续"形状不兼容"失败计数；跨 generator 实例不保留（插件重载即重试）。 */
+  let shapeFailures = 0
 
   const service = () => {
     const subagents = ctx.get?.('subagents')
@@ -238,6 +246,12 @@ export function createAgentGrouper(ctx, config, logger, sharedStats = undefined)
 
   /** 生成一次分组；失败返回 error（不抛）。 */
   async function generate({ agent, tools, previousGroups }) {
+    // 形状不兼容暂停：到期自动解除；期间不计数、不重试，继续用 last-known-good。
+    if (stats.paused !== undefined) {
+      if (Date.now() < stats.paused.retryAt) return { error: { code: stats.paused.code, message: stats.paused.message } }
+      delete stats.paused
+      shapeFailures = 0
+    }
     const subagents = service()
     if (subagents === undefined) {
       // 观测缺口修复：provider 不可用也计入 failures / lastError（否则状态里看不到真实失败原因）。
@@ -256,19 +270,22 @@ export function createAgentGrouper(ctx, config, logger, sharedStats = undefined)
       const attemptTimer = setTimeout(() => attemptController.abort(), timeoutMs)
       let activation
       try {
-        activation = await subagents.startActivation({
+        // 版本形状差异只在 subagent-compat.js 里处理：顶层字段服务 0.2.2-rc.2+，
+        // 不可枚举的 request 兼容 0.2.2-rc.1 及更早。
+        activation = await startSubagentActivation(subagents, {
           provider,
           label: 'agentic-tool-catalog generation',
-          request: {
-            parent: agent,
-            prompt: [{ type: 'text', text: buildAgentGroupPrompt(tools, { feedback, previousGroups: useIncremental ? previousGroups : undefined }) }],
-            maxDepth: 1,
-            outputSchema: AGENT_GROUP_SCHEMA,
-          },
+          parent: agent,
+          prompt: [{ type: 'text', text: buildAgentGroupPrompt(tools, { feedback, previousGroups: useIncremental ? previousGroups : undefined }) }],
+          maxDepth: 1,
+          outputSchema: AGENT_GROUP_SCHEMA,
           signal: attemptController.signal,
           delivery: 'caller',
         })
         const result = await activation.result
+        // 宿主接受了 spec 并返回结果：形状回退计数清零（即使下面校验失败，也与形状无关）。
+        shapeFailures = 0
+        delete stats.paused
         const structured = result?.structured
         const validated = validateAgentGroups(tools, structured)
         if (validated.error === undefined) {
@@ -287,8 +304,27 @@ export function createAgentGrouper(ctx, config, logger, sharedStats = undefined)
         return { error: validated.error }
       } catch (error) {
         const message = String(error?.message ?? error).slice(0, 160)
-        stats.lastError = { code: attemptController.signal.aborted ? 'TIMEOUT' : 'AGENT_FAILED', message, at: Date.now() }
+        const aborted = attemptController.signal.aborted
+        const shapeFailure = !aborted && isActivationShapeError(error)
+        if (shapeFailure) shapeFailures += 1
+        else if (!aborted) shapeFailures = 0
+        stats.lastError = {
+          code: aborted ? 'TIMEOUT' : shapeFailure ? 'UNSUPPORTED_HOST' : 'AGENT_FAILED',
+          message,
+          at: Date.now(),
+        }
         logger?.warn?.(`dsh-agentic-tool-catalog generation: ${message}`)
+        if (shapeFailure && shapeFailures >= SHAPE_FAILURE_PAUSE_THRESHOLD && stats.paused === undefined) {
+          // 软闸门：不为"宿主形状不认识"反复刷失败；保留 last-known-good，显式标 paused。
+          stats.paused = {
+            code: 'UNSUPPORTED_HOST',
+            message: `host rejected the ${ACTIVATION_SHAPES.join('+')} subagent activation spec (${message}); `
+              + 'automatic catalog generation paused for 1h; the last successful grouping keeps serving',
+            at: Date.now(),
+            retryAt: Date.now() + SHAPE_FAILURE_PAUSE_MS,
+          }
+          logger?.warn?.(`dsh-agentic-tool-catalog: ${stats.paused.message}`)
+        }
         stats.failures += 1
         return { error: stats.lastError }
       } finally {
@@ -302,5 +338,5 @@ export function createAgentGrouper(ctx, config, logger, sharedStats = undefined)
     return { error: stats.lastError ?? { code: 'UNKNOWN', message: 'generation failed' } }
   }
 
-  return { generate, stats, provider, enabled: () => service() !== undefined }
+  return { generate, stats, provider, activationShapes: ACTIVATION_SHAPES, enabled: () => service() !== undefined }
 }

package/lib/index.js

@@ -117,6 +117,9 @@ export function apply(ctx, config) {
   const instance = Symbol('instance')
   const shared = sharedState()
   const instanceId = ++shared.instanceSeq
+  // 新实例 = 新代码：不继承上一版留下的退避/暂停，否则热修后还要等 10 分钟才重试。
+  shared.failures.clear()
+  delete shared.agentStats.paused
   const registry = restrictionRegistry()
   const logger = ctx.logger
   const bootAt = Date.now() // 区分“进程启动后新建会话”（预热）与“恢复会话”（按需）
@@ -339,6 +342,16 @@ export function apply(ctx, config) {
       state.needsEnrichment = true
       return
     }
+    // 软闸门：宿主连续拒绝 activation spec 后暂停自动生成，继续用 last-known-good；
+    // 到期由 generate() 自动解除，插件重装也会清掉（见 apply 顶部）。
+    const paused = shared.agentStats.paused
+    if (paused !== undefined && Date.now() < paused.retryAt) {
+      state.needsEnrichment = true
+      if (!state.warnings.some((entry) => entry.kind === 'catalog-generation-paused')) {
+        state.warnings = [...state.warnings, { kind: 'catalog-generation-paused', message: paused.message }]
+      }
+      return
+    }
     const failedAt = shared.failures.get(cacheKey)
     if (failedAt !== undefined && Date.now() - failedAt < 600000) return // 10 分钟退避
 
@@ -516,6 +529,7 @@ export function apply(ctx, config) {
       generation: {
         provider: agentGrouper.provider,
         enabled: agentGrouper.enabled(),
+        activationShapes: agentGrouper.activationShapes,
         state: active ? 'running' : 'idle',
         ...shared.agentStats,
         instanceId,

package/lib/subagent-compat.js

@@ -0,0 +1,87 @@
+/**
+ * subagent-compat.js —— 唯一知道宿主 `ctx.subagents.startActivation()` 入参形状的地方。
+ *
+ * 背景（2026-11-12 实测）：
+ *   - DSH 0.2.1-rc.2 … 0.2.2-rc.1：请求字段装在 `spec.request` 里
+ *     （`{ provider, label, request: { parent, prompt, maxDepth, outputSchema, ... }, signal, delivery }`）；
+ *   - DSH 0.2.2-rc.2+：同一组字段被拍平到 spec 顶层，`startActivation` 直接读 `spec.parent.id`。
+ *
+ * 兼容策略：同时发送两种形状。
+ *   - 顶层字段服务 0.2.2-rc.2+；
+ *   - 不可枚举的 `request` 属性服务旧版（旧版只做属性读取 `spec.request`，仍可访问）；
+ *   - 不可枚举很重要：rc.2 的外部 provider 路径会把 spec 的剩余字段展开进 provider 请求，
+ *     可枚举的 `request` 会泄漏过去；不可枚举属性不会被展开。
+ *   - 两个版本的实现都只读自己认识的字段、不校验未知字段，因此并集是安全的。
+ *
+ * 这里是**唯一**允许出现版本形状差异的文件；其余代码只调用 `startSubagentActivation()`。
+ * 契约由 `scripts/verify-subagent-compat.mjs` 用真实的
+ * `@deepseek-ai/dsh-subagent@0.2.2-rc.1` / `@0.2.2-rc.2` 实现验证。
+ *
+ * @module @local/dsh-agentic-tool-catalog/subagent-compat
+ */
+
+/** 适配器同时支持的激活 spec 形状（用于状态观测；不代表宿主版本）。 */
+export const ACTIVATION_SHAPES = Object.freeze(['flat', 'nested'])
+
+/** 属于 `SubagentStartRequest`（随版本在顶层 / request 之间搬家的字段）。 */
+export const ACTIVATION_REQUEST_FIELDS = Object.freeze([
+  'cwd',
+  'agentPreset',
+  'prompt',
+  'parent',
+  'agentOptions',
+  'outputSchema',
+  'maxDepth',
+])
+
+/**
+ * 把扁平请求构造成两种宿主都能读的 activation spec。
+ * @param spec - 扁平请求（含 provider / label / signal / delivery 与 request 字段）。
+ * @returns 可直接传给 `ctx.subagents.startActivation()` 的 spec。
+ */
+export function buildSubagentActivationSpec(spec) {
+  const request = {}
+  for (const key of ACTIVATION_REQUEST_FIELDS) {
+    if (spec[key] !== undefined) request[key] = spec[key]
+  }
+  const activationSpec = {
+    provider: spec.provider,
+    label: spec.label,
+    ...(spec.name === undefined ? {} : { name: spec.name }),
+    ...(spec.childId === undefined ? {} : { childId: spec.childId }),
+    // 0.2.2-rc.2+：字段在顶层。
+    ...request,
+    signal: spec.signal,
+    delivery: spec.delivery,
+  }
+  // 0.2.1-rc.2 … 0.2.2-rc.1：字段在 request 里。不可枚举，避免 rc.2 的外部 provider 展开时泄漏。
+  Object.defineProperty(activationSpec, 'request', {
+    value: request,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  })
+  return activationSpec
+}
+
+/**
+ * 启动一个子代理激活，自动适配宿主的 spec 形状。
+ * @param subagents - `ctx.get('subagents')` 得到的服务。
+ * @param spec - 扁平请求（见 {@link ACTIVATION_REQUEST_FIELDS}）。
+ * @returns `startActivation()` 的原样结果。
+ */
+export function startSubagentActivation(subagents, spec) {
+  return subagents.startActivation(buildSubagentActivationSpec(spec))
+}
+
+/**
+ * 判断一个失败是否像"宿主不认识 activation spec 形状"（而非业务/模型失败）。
+ * 仅用于观测与软闸门：形状错误发生在创建子代理之前，无副作用。
+ * @param error - 捕获到的错误。
+ * @returns 是否匹配各版本读取缺失字段时的 TypeError。
+ */
+export function isActivationShapeError(error) {
+  if (!(error instanceof TypeError)) return false
+  const message = String(error.message ?? '')
+  return /Cannot read properties of undefined \(reading '(?:id|parent|prompt|request|maxDepth|outputSchema|cwd|agentPreset|agentOptions)'\)/.test(message)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agentic-tool-catalog",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Agentic Tool Catalog for DSH: an agent builds and maintains a tool catalog; schemas stay out of context and tools load on demand.",
   "icon": "./icon.svg",
   "type": "module",
@@ -80,11 +80,12 @@
   },
   "engines": {
     "node": ">=22.19.0",
-    "dsh": ">=0.2.1-rc.2 || >=0.2.2-rc.1"
+    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
   },
   "scripts": {
-    "test": "node scripts/verify-agentic-tool-catalog.mjs && node scripts/verify-agentic-tool-catalog-schema.mjs",
+    "test": "node scripts/verify-agentic-tool-catalog.mjs && node scripts/verify-agentic-tool-catalog-schema.mjs && node scripts/verify-subagent-compat.mjs",
     "test:schema": "node scripts/verify-agentic-tool-catalog-schema.mjs",
+    "test:compat": "node scripts/verify-subagent-compat.mjs",
     "pack:check": "npm pack --dry-run",
     "test:presentation": "node scripts/verify-presentation.mjs"
   }