dsh-plugin-prompt-tool 1.0.0 → 2.0.1

package/engine/actions/registration.mjs

@@ -0,0 +1,168 @@
+import { MAX_TRACKED_SESSIONS } from '../shared.mjs'
+import { subjectOf } from '../conditions/subject.mjs'
+import { ACTION_KINDS } from './catalog.mjs'
+
+export function channelBinder(ctx, kind, plugin, prepend) {
+  const legal = new Set(ACTION_KINDS[kind].events)
+  return (event, handler, options) => {
+    if (!legal.has(event)) {
+      throw new TypeError(`${plugin}: action ${kind} must not register on ${JSON.stringify(event)} — legal channel(s): ${[...legal].join(', ')}`)
+    }
+    // `prepend` 只表达「落在宿主 waterfall 的最外层」（否决型动作如预算剥离需要它），
+    // **不承担声明之间的排序**——同通道顺序由注册先后决定（见 trigger.mjs 的 R13 依据）。
+    return ctx.on(event, handler, prepend === true ? { ...options, prepend: true } : options)
+  }
+}
+
+const ON_REGISTERED_KINDS = new Set(['assembly', 'decision', 'append-context', 'sdk-strip', 'request-params', 'inbox-prepend', 'pre-step-filter'])
+
+/** 编辑目录与注册校验共用支持面；不另给客户端维护一份名单。 */
+export const actionSupportsWhen = (kind) => ON_REGISTERED_KINDS.has(kind)
+
+/**
+ * **没有 `next` 的通道**（官方 `@mode emit` / `@mode serial`）：注册在这些通道上的动作
+ * 不能靠「`args` 的最后一个参数是 `next`」工作——判定路径与载荷切分都要走无 `next` 分支。
+ *
+ * 依据（`@deepseek-ai/dsh-agent/lib/types/runtime-types.d.ts` 的逐事件 `@mode` 注释）：
+ * **只有 `waterfall` 才有 `next`**；`agent/pre-step`／`agent/request` 是 waterfall，
+ * 而 `agent/inbox/inserted`（B7 新增动作的通道）是 **emit**、
+ * `agent/turn-stopping`（既有 append-context「续跑」的通道）是 **serial**——
+ * 两者都没有 `next`。第三项此前是个隐患：`append-context(continue)` 一旦带 `when`，
+ * 旧实现会把 `turn` 当成 `next` 调掉。
+ */
+export const NEXT_FREE_CHANNELS = new Set([
+  'session/event',
+  'agent/inbox/inserted',
+  'agent/turn-stopping',
+])
+
+/** 动作的固定执行点；声明编译与 when 接线共用，不能用声明字段改变注册器。 */
+export function actionExecutionPoint(action) {
+  if (action.kind === 'decision') {
+    return { channel: action.phase === 'post' ? 'tools/post-execute' : 'tools/pre-execute', phase: 'before-next' }
+  }
+  if (action.kind === 'append-context') {
+    return action.mode === 'continue'
+      ? { channel: 'agent/turn-stopping', phase: 'before-next' }
+      : { channel: 'tools/post-execute', phase: 'after-next' }
+  }
+  if (action.kind === 'inject-text') {
+    const layer = action.config?.layer
+    const channel = {
+      'pre-step': 'agent/pre-step',
+      'system-section': 'system-prompt/assemble',
+      'runtime-context': 'system-prompt/assemble',
+      'agent-request': 'agent/request',
+      'llm-stream': 'llm/stream',
+      'turn-stop': 'agent/turn-stopping',
+      'subagent-start': 'subagent/start',
+      'subagent-end': 'subagent/end',
+    }[layer]
+    if (channel === undefined) {
+      throw new TypeError(`inject-text layer ${JSON.stringify(layer)} has no single trigger channel; tool-pipeline uses separate decision actions`)
+    }
+    return { channel, phase: ['pre-step', 'agent-request'].includes(layer) ? 'after-next' : 'before-next' }
+  }
+  const channel = ACTION_KINDS[action.kind].events[0]
+  return { channel, phase: NEXT_FREE_CHANNELS.has(channel) ? 'before-next' : 'after-next' }
+}
+
+/**
+ * 每轮生效预算（动作声明的 `maxPerTurn`）。
+ *
+ * **为什么必须是动作侧、不能用 `count` 原语**：原 `deliberation-gate` 的 `gates` 与原
+ * `progress-reminder` 的 `drips` 数的是**本动作自己生效了几次**，不是 durable 事件数。
+ * 它们是纯增量状态（重启后从 0 开始、每轮重置），而 `count` 的模型是冷扫 durable 事件流重建
+ * ——两者在重启/压缩后给出的答案不同，所以这是独立的一类计数。
+ *
+ * **轮号**取自 durable 事件的 `data.turn`（与 `predicates.mjs` 的 `trackTurn` 同规则：任何带
+ * 有限轮号的事件都推进当前轮并取最大值），所以重启后计数虽从 0 开始，轮边界立刻是对的。
+ *
+ * **同步消耗**：动作通过目标与有效结果检查后，紧邻实际效果同步 `take()`；
+ * claim 与效果之间没有 await，并行调用不得越过预算。
+ *
+ * @returns {{take: (subject: unknown) => boolean, observe: Function}|undefined} 无 `maxPerTurn` 时为 undefined
+ */
+export function createTurnBudget(max) {
+  if (max === undefined) return undefined
+  /** sessionId -> { turn, used }（纯增量，与原模块同语义：重启从 0 开始）。 */
+  const budgets = new Map()
+  const entryOf = (session) => {
+    if (session?.id === undefined) return undefined
+    let entry = budgets.get(session.id)
+    if (entry === undefined) {
+      if (budgets.size >= MAX_TRACKED_SESSIONS) budgets.clear()
+      entry = { turn: undefined, used: 0 }
+      budgets.set(session.id, entry)
+    }
+    return entry
+  }
+  return {
+    /** 同步查/增；`false` = 本轮预算已尽，调用方按「不命中」放行下游。 */
+    take(subject) {
+      const session = subject?.session ?? subject?.agent?.session
+      // 无会话不设限：与原模块「取不到会话条目即放行」的降级一致。
+      const entry = entryOf(session)
+      if (entry === undefined) return true
+      if (entry.used >= max) return false
+      entry.used += 1
+      return true
+    },
+    /** 轮边界重置（取最大值，容忍乱序/重复事件）。 */
+    observe(session, event) {
+      const turn = event?.data?.turn
+      if (typeof turn !== 'number' || !Number.isFinite(turn)) return
+      const entry = entryOf(session)
+      if (entry === undefined) return
+      if (entry.turn === undefined || turn > entry.turn) {
+        entry.turn = turn
+        entry.used = 0
+      }
+    },
+  }
+}
+
+/**
+ * 按动作实际阶段求值 when。after-next 先结算下游，再读取当前 epoch，
+ * 并向动作提供已结算结果，保证宿主 next 只调用一次；未命中或异常保持下游结果。
+ * 每轮预算由各动作在目标匹配且即将生效时同步 claim，不在谓词入口扣减。
+ *
+ * **同步谓词走同步路径**：`tools/pre-execute` 这类通道的裁决靠「deny 前无 await」保证
+ * 并行调用不越过预算（见 `deliberation-gate.mjs` 的注释），无条件 `await` 会破坏它。
+ * 返回 Promise 的谓词退回异步路径——声明编译出的谓词恒同步，这条兜底是给手写调用方的。
+ */
+export function withWhen(on, when, warnOnce, phase) {
+  if (typeof when !== 'function') return on
+  // 注意参数个数：`on` 的签名是 `(event, handler, options)`——包装后的处理器必须占据
+  // **第二个**位置，多传一个参数会把 options 挤到错位（首版就踩了这个，被测试抓出）。
+  return (event, handler, options) => on(event, (...args) => {
+    const nextFree = NEXT_FREE_CHANNELS.has(event)
+    const payload = nextFree ? args : args.slice(0, -1)
+    const pass = () => (nextFree ? undefined : args[args.length - 1]())
+    // 谓词契约是**单个载荷对象**（见 predicates.mjs 头部的统一接口），而处理器收到的是
+    // 事件参数表：按通道归一后再交给谓词——否则除 `names` 外，各原语在真实载荷上都
+    // 取不到它们要的域（`phase` 曾因此恒为「已晋升」、`count` 恒 0）。
+    const evaluate = (invoke, fallback) => {
+      const decide = (decided) => decided === true ? invoke() : fallback()
+      const failed = (error) => {
+        warnOnce(`when predicate failed: ${String(error?.message ?? error)}`)
+        return fallback()
+      }
+      let decided
+      try {
+        decided = when(subjectOf(event, payload, warnOnce))
+      } catch (error) {
+        return failed(error)
+      }
+      return decided !== null && typeof decided === 'object' && typeof decided.then === 'function'
+        ? decided.then(decide, failed)
+        : decide(decided)
+    }
+    if (!nextFree && phase === 'after-next') {
+      return Promise.resolve(pass()).then((result) => evaluate(
+        () => handler(...payload, () => result), () => result,
+      ))
+    }
+    return evaluate(() => handler(...args), pass)
+  }, options)
+}

package/engine/actions/request-params.mjs

@@ -0,0 +1,32 @@
+import { labelOf } from './shared.mjs'
+import { applyAgentRequestParams, matchesAgentScope } from '../layers.mjs'
+
+export function prepareRequestParams(action, plugin) {
+  const label = labelOf(action)
+  const patch = action.patch
+  if (patch !== undefined && (patch === null || typeof patch !== 'object' || Array.isArray(patch))) {
+    throw new TypeError(`${plugin}: ${label}.patch must be an object`)
+  }
+  const unset = action.unset
+  if (unset !== undefined && (unset === null || typeof unset !== 'object' || Array.isArray(unset))) {
+    throw new TypeError(`${plugin}: ${label}.unset must be an object of { key: expectedValue }`)
+  }
+  if (action.replace === true && unset !== undefined) {
+    throw new TypeError(`${plugin}: ${label} cannot combine replace with unset — 整体替换没有可比较的下游值`)
+  }
+  const params = { ...(patch !== undefined ? { patch } : {}), ...(unset !== undefined ? { unset } : {}), ...(action.replace === true ? { replace: true } : {}) }
+  return (_ctx, { warnOnce, on, collect, take }) => collect(on('agent/request', async (payload, next) => {
+    const base = await next()
+    try {
+      if (!matchesAgentScope(action, payload?.agent)) return base
+      const result = applyAgentRequestParams(params, base)
+      const keys = Object.keys(result)
+      const changed = base == null || keys.length !== Object.keys(base).length
+        || keys.some((key) => !Object.hasOwn(base, key) || !Object.is(result[key], base[key]))
+      return changed && take(payload) ? result : base
+    } catch (error) {
+      warnOnce(`${plugin}: request-params action ${label} failed: ${String(error?.message ?? error)}`)
+      return base
+    }
+  }))
+}

package/engine/actions/sdk-strip.mjs

@@ -0,0 +1,30 @@
+import { labelOf, createMask } from './shared.mjs'
+import { SDK_SECTION_NAME, sdkToolNames, stripSdkDeclarations } from '../sdk-strip.mjs'
+
+export function prepareSdkStrip(action, plugin) {
+  const label = labelOf(action)
+  const mask = createMask(action.mask ?? action, `${label}.mask`, plugin)
+  return (_ctx, { warnOnce, on, collect, take }) => collect(on('system-prompt/assemble', async (assembly, context, next) => {
+    // Downstream errors propagate untouched; only this action's own logic is guarded.
+    const assembled = await next()
+    try {
+      if (!Array.isArray(assembled.sections)) return assembled
+      let changed = false
+      const sections = assembled.sections.map((section) => {
+        if (section?.name !== SDK_SECTION_NAME || typeof section.text !== 'string') return section
+        const names = mask.allow === undefined
+          ? mask.deny
+          : new Set([...sdkToolNames(section.text)].filter((toolName) => mask.blocks(toolName)))
+        if (names === undefined || names.size === 0) return section
+        const stripped = stripSdkDeclarations(section.text, names)
+        if (stripped === section.text) return section
+        changed = true
+        return { ...section, text: stripped }
+      })
+      return changed && take(context) ? { ...assembled, sections } : assembled
+    } catch (error) {
+      warnOnce(`${plugin}: sdk-strip action ${label} failed, keeping the original SDK text: ${String(error?.message ?? error)}`)
+      return assembled
+    }
+  }))
+}

package/engine/actions/shared.mjs

@@ -0,0 +1,71 @@
+import { stringList } from '../fields.mjs'
+import { parseToolNames } from '../shared.mjs'
+export const RUN_CODE = 'run_code'
+
+export const NAME_LIST = stringList({ as: 'set', dedupe: true, allowEmpty: true })
+
+/** 动作标签（错误消息与 source.plugin 命名空间）。 */
+export const labelOf = (action) => (typeof action?.id === 'string' && action.id.length > 0 ? action.id : String(action?.kind ?? 'action'))
+
+/**
+ * 名单判据的唯一实现：presentation 过滤与执行 guard 共用（呈现与执行不得两套口径）。
+ *
+ * 第四个参数 `allowExtra` 是**可选的活集合**（`assembly.tools.allowFrom` 的动态白名单）：
+ * 调用方持有它，在每个请求解析完历史工具调用后 `clear()` + 填充。它**只做加法**——多一个
+ * 名字就多一个工具通过，永远不能剔除任何工具。这不是巧合，而是判据方向决定的：`blocks()`
+ * 的语义是「**在** allow 里就放行」，所以任何动态集合都只可能解锁。
+ *
+ * 未声明静态 `allow`、只声明 `allowFrom` 时，allow 视为空集（`blocks` 仍会裁掉没被解锁的）。
+ */
+export function createMask(source, label, plugin, allowExtra) {
+  const allow = NAME_LIST.parse(source?.allow, plugin, `${label}.allow`)
+  const deny = NAME_LIST.parse(source?.deny, plugin, `${label}.deny`)
+  if (allow !== undefined && deny !== undefined) {
+    throw new TypeError(`${plugin}: ${label} cannot combine allow with deny`)
+  }
+  if (allow === undefined && deny === undefined && allowExtra === undefined) {
+    throw new TypeError(`${plugin}: ${label} needs allow and/or deny — 空名单无法表达「剔哪些工具」`)
+  }
+  // `run_code` 是 PTC 呈现**唯一**的可调用入口（见本文件顶部）。把它写进 **deny** 名单会让
+  // 整个 PTC 面失效，一律挂载期拒绝。写进 **allow** 名单相反是**必需**的：allow 是
+  // fail-closed（未列出即剔出），不点名它就会被连带剔掉——PTC 预设因此失去唯一入口。
+  // 2026-09-22 用户拍板：allow 模式允许点名它（旧模块本就能把它写进白名单）。
+  if (deny?.has(RUN_CODE)) {
+    throw new TypeError(`${plugin}: ${label}.deny must not name the reserved ${RUN_CODE} transport — it is the only callable entry of the PTC presentation`)
+  }
+  return {
+    /** 静态 allow（原样保留；动态项不并入，免得调用方误以为它是静态声明）。 */
+    allow,
+    deny,
+    /** 动态白名单的落点（活集合，由调用方每轮重填）；未声明 allowFrom 时不存在。 */
+    allowExtra,
+    /**
+     * fail-open 兜底开关（**可选**，缺省 false）：原 `tool-bootstrap` 的语义是
+     * 「keep 名单里的工具在本次装配目录里一个都不存在 → 放弃裁剪、暴露完整目录」（声明侧见
+     * `test/engine/declarations/tool-bootstrap.yml` 的 `requireMatch: true`），而原
+     * `tool-filter` 的同名场景是**照名单裁成空目录**。两种语义都真实存在，所以这里
+     * **不设默认**——要兜底的声明自己写 `requireMatch: true`。把某一个模块的特有语义当成
+     * 通用默认，会让另一个声明路径的行为被悄悄改掉（这正是对拍抓出来的）。
+     */
+    requireMatch: source?.requireMatch === true,
+    /** 与 tool-filter 的名单判据 / Layer.admits 同一判据（tool-filter 模块已删除，判据保留）。 */
+    blocks: (toolName) => {
+      if (typeof toolName !== 'string' || toolName.length === 0) return false
+      if (deny !== undefined && deny.has(toolName)) return true
+      if (allowExtra?.has(toolName) === true) return false
+      // 声明了 allow、或声明了 allowFrom（= 白名单模式，静态名单视为空集），未点名即裁掉。
+      return (allow !== undefined || allowExtra !== undefined) && allow?.has(toolName) !== true
+    },
+  }
+}
+
+export function requireString(value, label, plugin) {
+  if (typeof value !== 'string') throw new TypeError(`${plugin}: ${label} must be a string`)
+  return value
+}
+
+export function toolNameSet(value, plugin, field) {
+  if (value === undefined) return undefined
+  const names = NAME_LIST.parse(typeof value === 'string' ? parseToolNames(value) : value, plugin, field)
+  return names !== undefined && names.size > 0 ? names : undefined
+}