dsh-plugin-prompt-tool 1.0.0 → 2.0.0

package/engine/branch.mjs

@@ -0,0 +1,44 @@
+/**
+ * 分支语法的唯一展开器：`if`/`then`/`else` 是当前名，`when`/`do` 是兼容输入。
+ *
+ * 规则（`rule-spec.mjs`）与触发器声明（`trigger-spec.mjs`）共用这一份实现——
+ * 两套入口必须是同一套语义，否则同一个模块换个入口就换行为。
+ */
+
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+/** 分支节点：占动作位、没有 `kind`，但带 `if`/`then`/`else` 之一。 */
+export const isBranchNode = node => record(node) && node.kind === undefined
+  && (node.if !== undefined || node.then !== undefined || node.else !== undefined)
+
+/** 多个条件按声明序合取；空数组 = 无条件（`compileWhen(undefined)` 直接返回 undefined）。 */
+export function conjunction(conditions) {
+  if (conditions.length === 0) return undefined
+  return conditions.length === 1 ? conditions[0] : { all: [...conditions] }
+}
+
+/**
+ * 把一份动作声明展开为扁平的「动作 + 自身分支条件」列表。
+ *
+ * - 普通动作原样带出，分支条件 = `outer` 的合取（空 = 无条件）；
+ * - 分支节点的 `then` 追加本层 `if`、`else` 追加 `not(if)`——互斥由结构保证，不由作者手写；
+ * - 返回顺序即声明序（then 在前、else 在后）；
+ * - `bypass` 标记该动作来自**声明级** `else`：它的条件已含 `not(if)`，不能再叠加声明级判定。
+ */
+export function expandActions(list, options = {}, label) {
+  if (!Array.isArray(list)) throw new TypeError(`${label} must be an array`)
+  const { outer = [], bypass = false } = options
+  const out = []
+  for (const [index, node] of list.entries()) {
+    const at = `${label}[${index}]`
+    if (isBranchNode(node)) {
+      if (node.if === undefined) throw new TypeError(`${at}: a branch needs if`)
+      if (node.then === undefined) throw new TypeError(`${at}: a branch needs then`)
+      out.push(...expandActions(node.then, { outer: [...outer, node.if], bypass }, `${at}.then`))
+      if (node.else !== undefined) out.push(...expandActions(node.else, { outer: [...outer, { not: node.if }], bypass }, `${at}.else`))
+      continue
+    }
+    out.push({ node, conditions: outer, bypass })
+  }
+  return out
+}

package/engine/compaction-epoch.mjs

@@ -23,7 +23,7 @@
  *
  * GATE MODE (strict two-phase stabilization extension, source: xiaobright/dsh-anchored-standard
  * MIT + phase-1 quarantine): `promoteGate: true` gates the promotion on the
- * first reasoning block classifying minimal-like (`we` present, no `let me`),
+ * first reasoning block matching the caller's positive and negative patterns,
  * with a `maxPromoteSteps` fallback supplied by the caller's config; `promoteAfterFirstResponse:
  * true` promotes a tool-less first response once it has responded, and also
  * releases an anchor-gated session when its first turn ends. Gate mode uses
@@ -34,24 +34,41 @@
 
 import { sessionEvents, sessionState } from './shared.mjs'
 
-/** 首段 reasoning 块分类（严格门控扩展）：we 且无 let me = minimal-like。 */
-export function classifyReasoning(text) {
-  const trimmed = String(text ?? '').trim()
-  const we = [...trimmed.matchAll(/\bwe\b/gi)].length
-  const letMe = [...trimmed.matchAll(/\blet me\b/gi)].length
-  const metrics = { we, letMe }
-  if (we > 0 && letMe === 0) return { label: 'minimal-like', score: 4, metrics }
-  if (letMe > 0) return { label: 'standard-like', score: -4, metrics }
-  return { label: 'ambiguous', score: 0, metrics }
+/** 匹配内容与大小写均由调用方显式声明；空 pattern 不承担任何业务识别。 */
+function reasoningClassifier(options = {}) {
+  const flags = options.reasoningFlags ?? ''
+  if (typeof flags !== 'string') throw new TypeError('reasoningFlags must be a string')
+  const compile = (key) => {
+    const pattern = options[key]
+    if (pattern == null || pattern === '') return undefined
+    if (typeof pattern !== 'string') throw new TypeError(`${key} must be a string`)
+    return new RegExp(pattern, flags.includes('g') ? flags : `${flags}g`)
+  }
+  const positive = compile('reasoningPattern')
+  const negative = compile('reasoningNegativePattern')
+  return text => {
+    const trimmed = String(text ?? '').trim()
+    // 旧诊断返回字段保留；两项现在分别计数调用方的正、负模式。分数不参与晋升。
+    const we = positive === undefined ? 0 : [...trimmed.matchAll(positive)].length
+    const letMe = negative === undefined ? 0 : [...trimmed.matchAll(negative)].length
+    const metrics = { we, letMe }
+    if (we > 0 && letMe === 0) return { label: 'minimal-like', score: 4, metrics }
+    if (letMe > 0) return { label: 'standard-like', score: -4, metrics }
+    return { label: 'ambiguous', score: 0, metrics }
+  }
 }
 
+export function classifyReasoning(text, options = {}) { return reasoningClassifier(options)(text) }
+
 /** 首段 reasoning 块是否为 minimal-like（后续块不覆盖首个标准样块）。 */
-export function hasAnchoredReasoning(content) {
+function firstReasoningMatches(content, classify) {
   if (!Array.isArray(content)) return false
   const first = content.find((block) => block?.type === 'reasoning')
-  return first !== undefined && classifyReasoning(first.text).label === 'minimal-like'
+  return first !== undefined && classify(first.text).label === 'minimal-like'
 }
 
+export function hasAnchoredReasoning(content, options = {}) { return firstReasoningMatches(content, reasoningClassifier(options)) }
+
 /** True only when compaction completed and changed the model-visible surface. */
 export function isSuccessfulCompactionEnd(event) {
   return event?.type === 'compaction/end' && event.data?.error === undefined
@@ -62,6 +79,7 @@ export function createEpochPromotion(promoteEvents, options = {}) {
   const includeSubagents = options.includeSubagents === true
   const promoteGate = options.promoteGate === true
   const promoteAfterFirstResponse = options.promoteAfterFirstResponse === true
+  const classify = reasoningClassifier(options)
   // 门控回退步数由调用方配置提供（tool-bootstrap 在开启门控时做必填校验）：
   // 引擎不内置默认；未提供时步数兜底不生效，只按 anchored 判定。
   const maxPromoteSteps = options.maxPromoteSteps
@@ -115,7 +133,7 @@ export function createEpochPromotion(promoteEvents, options = {}) {
       else if (event.type === 'turn/end') entry.turnEnded = true
       else if (event.type === 'assistant/message') {
         entry.responded = true
-        if (!entry.anchored) entry.anchored = hasAnchoredReasoning(event.data?.message?.content)
+        if (!entry.anchored) entry.anchored = firstReasoningMatches(event.data?.message?.content, classify)
       }
       if (decideGate(entry)) entry.promoted = true
       return entry

package/engine/compositions/source/local/dev-tool-search.yml

@@ -0,0 +1,11 @@
+# module: dev-tool-search
+# source: engine/compositions/source/local/dev-tool-search.yml (本地附加,非官方模块)
+#
+# 工具面的按需发现与解锁。与 assembly 动作的 allowFrom 配对使用：
+#   本工具把解锁名写进持久 tool/call 参数 → allowFrom 读回 → 下次请求起生效。
+# 只挂本行而不配 allowFrom 的话，解锁是一次性的（当次请求用完即被裁掉）。
+#
+# 常驻集由模板声明（见 templates/ 的工具面收窄模板），本行只负责发现入口。
+
+- id: dev-tool-search
+  name: ./engine/dev-tool-search.mjs

package/engine/compositions/source/local/instruction-hint.yml

@@ -6,10 +6,31 @@
 # opt-in：enabled 默认 false（与原 instructionHint 默认 false 同值），由参数桥
 # params.instructionHint（→ 本行 enabled）或本行 config.enabled: true 打开；
 # 相位词汇与 tool-bootstrap / promoted-code-mode 同源（compaction-epoch.mjs）。
+#
+# 四个模板必须随行给全（2026-10-05 修）：`instruction-hint.mjs#apply` 的首行是
+#   `if (!enabled || templateOf(source, 'messageTemplate').trim().length === 0) return`
+# 而本行此前只配了 enabled/promoteOn/includeSubagents —— 于是把开关打开**不注册任何
+# 转换**：配置合法、零效果、零报错（与 count.delegated 的静默失效同类）。模板正文取自
+# templates/policies/legacy-defaults.yml#instructionHint，与 rules-migration.ts:102
+# 的迁移默认值同源；两处必须一致，否则「迁移进来的定义」与「新装的组合源」行为分叉。
+# legacy-defaults.yml 自身标注「引擎运行时不得读取」，所以这里必须是实体而非引用。
+#
+# includeSubagents: true —— 子代理首次请求即视为已晋升（官方相位语义），所以子代理
+# 从第 1 轮就拿提示而非全文。主会话则是首个工具调用/助手消息之后才降级（promoteOn）。
 
 - id: instruction-hint
   name: ./engine/instruction-hint.mjs
   config:
     enabled: false
     promoteOn: either
-    includeSubagents: false
+    includeSubagents: true
+    projectTemplate: "Reference documents exist: {{FILES}} (project root: {{ROOT}})."
+    globalTemplate: "A user reference document exists: {{FILES}}."
+    suffixTemplate: They are reference documents about the user's environment and
+      workspace conventions, not task instructions. Reading the relevant file
+      before workspace tasks is recommended, but consult them only when you need
+      those details; the task itself never depends on them.
+    messageTemplate: |-
+      <system-reminder>
+      Reference documents exist: {{FILES}}. {{SUFFIX}}
+      </system-reminder>

package/engine/compositions/source/local/rule-engine.yml

@@ -0,0 +1,6 @@
+# module: rule-engine
+# 单一规则分发入口；插件配装通道直接挂载同一编译器时跳过此行。
+- id: rule-engine
+  name: ./engine/rule-engine.mjs
+  config:
+    rulesFile: ../rules.yml

package/engine/condition.mjs

@@ -14,7 +14,7 @@
 import { extractText, sessionEvents } from './shared.mjs'
 
 /** subject → 载荷字段名。改这里等于改所有层的匹配对象。 */
-const SUBJECT_FIELDS = {
+export const SUBJECT_FIELDS = {
   toolArgs: 'argsText',
   toolResult: 'resultText',
   userMessage: 'userText',
@@ -54,11 +54,24 @@ export function toolArgsText(args) {
   }
 }
 
-/** pre-step 的缺省匹配对象：本批用户消息的文本。 */
+/**
+ * pre-step 的缺省匹配对象：本批**真实对话**的用户消息文本。
+ *
+ * 只收真人输入：引擎自己注入的消息同样是 user-role（`executor.mjs` 的
+ * `role: PRE_STEP_ROLE`、`pluginMessage` 的 `source` 是 `plugin:<name>` 生产者身份），
+ * 把它们算进来会让 `text.match` 匹配到自己注入过的正文——规则正文里出现「重构」
+ * 「实现」这类词就会自我命中，且命中判定在去重之前，`dedupe` 挡不住。
+ * 过滤判据与 `st-world-book.mjs#stChatMessages` 的同名约定一致（那是最早做对的一处），
+ * 两处必须保持同语义。
+ */
 export function userMessagesText(messages) {
   if (!Array.isArray(messages)) return ''
   return messages
-    .filter((message) => message?.role === 'user')
+    .filter((message) => message?.role === 'user'
+      && message.source?.plugin === undefined
+      && message.source?.kind !== 'plugin'
+      && !(typeof message.source?.kind === 'string' && message.source.kind.startsWith('plugin:'))
+      && (message.source?.kind === undefined || message.source.kind === 'user'))
     .map((message) => extractText(message))
     .filter((text) => text.length > 0)
     .join('\n')

package/engine/conditions/anchor.mjs

@@ -0,0 +1,32 @@
+import { createAnchorMatcher } from '../anchor-match.mjs'
+import { sessionEvents, sessionState } from '../shared.mjs'
+import { sessionOf } from './subject.mjs'
+import { boundOf, keyList } from './values.mjs'
+
+/** 首条 assistant reasoning 的确认事实；未到达时不缓存，无 id 会话不共享状态。 */
+export function createAnchorState(options = {}) {
+  const matcher = createAnchorMatcher({ keys: keyList(options.keys, 'anchor.keys'), mode: 'prefix' })
+  const confirmedBySession = sessionState(undefined, () => false)
+  return session => {
+    const assistants = sessionEvents(session).filter(event => event.type === 'assistant/message')
+    let confirmed = confirmedBySession.peek(session)
+    if (confirmed === undefined && assistants.length > 0) {
+      const reasoning = (assistants[0].data?.message?.content ?? []).find(block => block.type === 'reasoning')
+      confirmed = reasoning !== undefined && matcher.scan(String(reasoning.text ?? '')).active
+      confirmedBySession.set(session, confirmed)
+    }
+    return { confirmed: confirmed === true, assistantRounds: assistants.length }
+  }
+}
+
+/** 确认即命中；可选 fallbackAfter 表示超过指定 assistant 消息数后也允许。 */
+export function createAnchorPredicate(options = {}) {
+  const inspect = createAnchorState(options)
+  const fallbackAfter = boundOf(options.fallbackAfter, 'anchor.fallbackAfter')
+  const predicate = payload => {
+    const status = inspect(sessionOf(payload))
+    return status.confirmed || (fallbackAfter !== undefined && status.assistantRounds > fallbackAfter)
+  }
+  predicate.kind = 'anchor'
+  return predicate
+}

package/engine/conditions/availability.mjs

@@ -0,0 +1,47 @@
+import { agentOf, sessionOf } from './subject.mjs'
+import { SUBJECT_FIELDS } from '../condition.mjs'
+
+/** 缺少真实事件事实不是 false；尤其不能经 not 反转成允许。 */
+export const UNAVAILABLE = Symbol('condition-input-unavailable')
+
+export function conditionInputAvailable(kind, options, payload) {
+  const agent = agentOf(payload)
+  const session = sessionOf(payload)
+  if (['phase', 'count', 'session', 'anchor'].includes(kind)) {
+    return session != null && typeof session.snapshotEvents === 'function' && (kind !== 'phase' || agent?.session != null)
+  }
+  if (kind === 'preset') return agent?.ctx != null
+  if (kind === 'names') {
+    const name = typeof payload === 'string' ? payload : payload?.name
+    return typeof name === 'string' && name.length > 0
+  }
+  if (kind === 'source') return payload?.source !== null && typeof payload?.source === 'object' && !Array.isArray(payload.source)
+  if (kind === 'text') {
+    if (typeof payload === 'string') return true
+    const field = Object.hasOwn(SUBJECT_FIELDS, options.subject) ? SUBJECT_FIELDS[options.subject] : undefined
+    if (field === undefined || typeof payload?.[field] !== 'string') return false
+    // 归一化器可把缺载荷投影为空文本；保留原参数表时必须区分缺事实与确实为空。
+    if (Array.isArray(payload.args)) {
+      if (options.subject === 'toolArgs') return payload.args[0] != null && Object.hasOwn(payload.args[0], 'arguments')
+      if (options.subject === 'toolResult') return payload.args.length > 1 && payload.args[1] !== undefined
+      if (options.subject === 'userMessage' && payload.channel === 'agent/pre-step') return Array.isArray(payload.args[0]?.messages)
+      if (options.subject === 'userMessage' && payload.channel === 'agent/inbox/inserted') return payload.args[0]?.message != null
+      if (options.subject === 'assistantText') return typeof session?.snapshotEvents === 'function'
+      if (options.subject === 'subagentInfo') return payload.args[0] != null
+    }
+    return true
+  }
+  if (kind === 'scope') {
+    if (options.audience !== undefined && session == null) return false
+    const model = payload?.model ?? agent?.options?.model
+    if (options.modelScope !== undefined && options.modelScope !== 'all' && (typeof model !== 'string' || model.length === 0)) return false
+  }
+  return true
+}
+
+export function withAvailableInput(kind, options, predicate) {
+  const wrapped = payload => conditionInputAvailable(kind, options, payload) ? predicate(payload) : UNAVAILABLE
+  wrapped.kind = predicate.kind
+  if (typeof predicate.observe === 'function') wrapped.observe = (session, event) => predicate.observe(session, event)
+  return wrapped
+}

package/engine/conditions/composite.mjs

@@ -0,0 +1,83 @@
+import { MATCH_LOGIC } from '../anchor-match.mjs'
+import { UNAVAILABLE } from './availability.mjs'
+const COMPOSITE_OPERATORS = Object.values(MATCH_LOGIC)
+
+export function composite(node) {
+  if (typeof node === 'function') return node
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) {
+    throw new TypeError(`predicates: a composite must be a predicate or { ${COMPOSITE_OPERATORS.join(' | ')} }`)
+  }
+  const unknown = Object.keys(node).filter((key) => !COMPOSITE_OPERATORS.includes(key))
+  if (unknown.length > 0) {
+    throw new TypeError(`predicates: unknown composite key(s) ${unknown.join(', ')} — allowed: ${COMPOSITE_OPERATORS.join(', ')}`)
+  }
+  const declared = COMPOSITE_OPERATORS.filter((key) => node[key] !== undefined)
+  if (declared.length !== 1) {
+    throw new TypeError(`predicates: a composite node must declare exactly one of ${COMPOSITE_OPERATORS.join(', ')}`)
+  }
+  const operator = declared[0]
+  if (operator === MATCH_LOGIC.NOT) {
+    const child = composite(node[operator])
+    const predicate = (payload) => {
+      const result = child(payload)
+      return result === UNAVAILABLE ? UNAVAILABLE : !result
+    }
+    predicate.kind = 'composite'
+    if (typeof child.observe === 'function') {
+      predicate.observe = (session, event) => child.observe(session, event)
+    }
+    return predicate
+  }
+  const list = node[operator]
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new TypeError(`predicates: composite ${operator} needs a non-empty array of predicates`)
+  }
+  const children = list.map(composite)
+  const predicates = {
+    [MATCH_LOGIC.ANY]: (payload) => {
+      let unknown = false
+      for (const child of children) {
+        const result = child(payload)
+        if (result === UNAVAILABLE) unknown = true
+        else if (result) return true
+      }
+      return unknown ? UNAVAILABLE : false
+    },
+    [MATCH_LOGIC.ALL]: (payload) => {
+      let unknown = false
+      for (const child of children) {
+        const result = child(payload)
+        if (result === UNAVAILABLE) unknown = true
+        else if (!result) return false
+      }
+      return unknown ? UNAVAILABLE : true
+    },
+    [MATCH_LOGIC.NOT_ANY]: (payload) => {
+      let unknown = false
+      for (const child of children) {
+        const result = child(payload)
+        if (result === UNAVAILABLE) unknown = true
+        else if (result) return false
+      }
+      return unknown ? UNAVAILABLE : true
+    },
+  }
+  const predicate = predicates[operator]
+  if (predicate === undefined) {
+    throw new TypeError(`predicates: composite ${operator} is not a supported operator`)
+  }
+  predicate.kind = 'composite'
+  // 组合层必须**转发子谓词的 observe**（B7 T1 的跨能力缺口修复）：两条挂载路径的观察器
+  // 接线都按 `when.observe` 过滤（`trigger.mjs` 的 `wireTriggerObservers`），被组合包住的
+  // phase / count / session 谓词否则永远收不到活的 `session/event`——状态按 `session.id`
+  // 缓存后不再重扫（`shared.mjs` 的 `sessionMapGet`），判定会停在冷扫那一刻（计数恒旧值、
+  // 相位永不晋升）。`phase` 有 `subscribe: false` 可绕（代价是每次判定冷扫），
+  // `count` / `session` 没有该档，所以这条转发是它们唯一的活路。
+  const observers = children.filter((child) => typeof child.observe === 'function')
+  if (observers.length > 0) {
+    predicate.observe = (session, event) => {
+      for (const child of observers) child.observe(session, event)
+    }
+  }
+  return predicate
+}

package/engine/conditions/count.mjs

@@ -0,0 +1,140 @@
+import { MAX_TRACKED_SESSIONS, extractText, isDelegated, sessionEvents } from '../shared.mjs'
+import { sessionOf } from './subject.mjs'
+import { boundOf, optionalBoolean } from './values.mjs'
+
+const COUNT_SIGNALS = {
+  'tool-call': { type: 'tool/call', measure: 'count' },
+  'tool-result': { type: 'tool/result', measure: 'count' },
+  'assistant-message': { type: 'assistant/message', measure: 'count' },
+  'assistant-chars': { type: 'assistant/message', measure: 'chars' },
+  'user-message': { type: 'user/message', measure: 'count' },
+  turn: { type: 'turn/start', measure: 'count' },
+}
+
+/** 每会话最多保留的轮次计数（与 deliberation-gate 的 MAX_TRACKED_TURNS 同策略）。 */
+const MAX_TRACKED_TURNS = 8
+
+/** 轮边界事件：`per: 'turn'` 的当前轮由它与计数信号自身的轮号共同推进。 */
+const TURN_EVENT = 'turn/start'
+
+/**
+ * 计数判断：次数 / 字符数 / 轮次，带上下限与**冷启动重建**。
+ *
+ *  - `per: 'session'` 计整个 durable log；`per: 'turn'` 只计**最新轮**，当前轮由
+ *    `turn/start` 与计数信号自身带轮号的事件共同推进（与 deliberation-gate 的
+ *    `turnOf` 同规则），轮号取自 `event.data.turn`；无轮号的事件不参与轮内计数
+ *    （宁可少计，也不把跨轮数据算进当前轮）。
+ *  - 冷启动：首次判定冷扫 `sessionEvents(session)` 重建（重启/恢复/重挂后同一结果），
+ *    之后 O(1)；`observe` 是增量喂入，**只喂已判定过的会话**，避免「冷扫 + 增量」重复计数。
+ *  - 上下限：`count >= min`（声明时）且 `count <= max`（声明时）。至少要声明一侧，
+ *    否则该判定恒真——那是把配置错误伪装成命中。
+ *  - 取不到会话 = 无事件 = 计数 0（与空会话同一语义，不发明数据）；无 `id` 的会话
+ *    不记账（共享一个 Map 键会让两个会话串味），每次冷扫。
+ *
+ * @param {object} options
+ * @param {'tool-call'|'tool-result'|'assistant-message'|'assistant-chars'|'user-message'|'turn'} options.of
+ * @param {'session'|'turn'} [options.per] 缺省 session
+ * @param {number} [options.min]
+ * @param {number} [options.max]
+ * @returns {((payload: unknown) => boolean) & { kind: string, observe: Function }}
+ */
+export function createCountPredicate(options = {}) {
+  const signal = COUNT_SIGNALS[options.of]
+  if (signal === undefined) {
+    throw new TypeError(`predicates: count of must be one of ${Object.keys(COUNT_SIGNALS).join(', ')}`)
+  }
+  const per = options.per ?? 'session'
+  if (per !== 'session' && per !== 'turn') {
+    throw new TypeError('predicates: count per must be "session" or "turn"')
+  }
+  const min = boundOf(options.min, 'min')
+  const max = boundOf(options.max, 'max')
+  // 节奏判据（2026-09-22 用户拍板⑤「改用可重建计数」的核心语义）：`every: N` = 每 N 次命中一次。
+  // 原 `progress-reminder` 的 `results % every === 0` 配的是**自增后**的计数
+  // （声明侧见 `test/engine/declarations/progress-reminder.yml` 的 `count.every`），
+  // 所以这里必须要求 `count > 0`——否则 `0 % N === 0` 会让第 0 次就命中。
+  const every = options.every === undefined
+    ? undefined
+    : Number.isSafeInteger(options.every) && options.every > 0
+      ? options.every
+      : (() => { throw new TypeError('predicates: count every must be a positive integer') })()
+  if (min === undefined && max === undefined && every === undefined) {
+    throw new TypeError('predicates: a count predicate needs min, max or every')
+  }
+  // 计数时点对齐（2026-09-22 用户拍板「扩原语」）：某些通道的 `when` 在**处理器入口**求值，
+  // 早于本次信号事件落盘——`tools/post-execute` 就是 `dsh-tools` 的
+  // `finalizeScheduledExecution` 内部一环，而该包内不写 durable `tool/result`，落盘发生在
+  // `execute()` 返回后的 agent loop。`includeCurrent: true` 把「本次触发即将成为的那个事件」
+  // 计入，从而与模块自己的自增计数时点对齐。
+  // **适用边界由声明者负责**：谓词看不到通道名，只有在「当前事件即将成为该信号」的通道上
+  // 这个 +1 才成立（post-execute 上的 tool-result 成立；pre-execute 上的 tool-result 不成立）。
+  const includeCurrent = optionalBoolean(options.includeCurrent, 'includeCurrent', false)
+  // 受众判据（与 `session` 谓词的 `delegated` 同语义、同实现 `shared.isDelegated`）。
+  // 需求的来源是原 `deliberation-gate` 与原 `progress-reminder`：这两个能力的
+  // **主判据就是 count**，受众不能只挂在 `session` 谓词上——那会迫使声明额外耦合一个
+  // durable 事件类型（还要回答「哪种 type 恒真」，而哨兵轮表明甚至可能没有轮事件）。
+  const delegated = optionalBoolean(options.delegated, 'delegated', undefined)
+  /** sessionId -> { total, turns, lastTurn }（进程内快路径，真相在 durable 事件流）。 */
+  const state = new Map()
+  const fresh = () => ({ total: 0, turns: new Map(), lastTurn: undefined })
+  const measure = (event) => (signal.measure === 'chars' ? extractText(event.data).length : 1)
+  /** 轮号推进：与 deliberation-gate 的 turnOf/turnEntryOf 同规则——`turn/start` 与
+   *  计数信号自身带轮号的事件都推进当前轮，且取最大值；新轮先落 0，再累加。 */
+  const trackTurn = (entry, turn) => {
+    if (!entry.turns.has(turn)) {
+      if (entry.turns.size >= MAX_TRACKED_TURNS) {
+        const oldest = [...entry.turns.keys()]
+          .sort((left, right) => left - right)
+          .slice(0, entry.turns.size - MAX_TRACKED_TURNS + 1)
+        for (const key of oldest) entry.turns.delete(key)
+      }
+      entry.turns.set(turn, 0)
+    }
+    if (entry.lastTurn === undefined || turn > entry.lastTurn) entry.lastTurn = turn
+  }
+  const applyEvent = (entry, event) => {
+    const type = event?.type
+    const turn = event?.data?.turn
+    const tagged = typeof turn === 'number' && Number.isFinite(turn)
+    if (per === 'turn' && tagged && (type === TURN_EVENT || type === signal.type)) trackTurn(entry, turn)
+    if (type !== signal.type) return entry
+    const amount = measure(event)
+    if (per === 'session') {
+      entry.total += amount
+      return entry
+    }
+    // 轮内计数只认带轮号的事件（与 deliberation-gate 一致：宁可少计，也不把跨轮数据算进当前轮）。
+    if (!tagged) return entry
+    entry.turns.set(turn, (entry.turns.get(turn) ?? 0) + amount)
+    return entry
+  }
+  const countOf = (entry) => (per === 'session'
+    ? entry.total
+    : (entry.lastTurn === undefined ? 0 : entry.turns.get(entry.lastTurn) ?? 0))
+  const rebuild = (session) => {
+    const entry = fresh()
+    for (const event of sessionEvents(session)) applyEvent(entry, event)
+    return entry
+  }
+  const entryOf = (session) => {
+    if (session?.id === undefined) return rebuild(session)
+    const known = state.get(session.id)
+    if (known !== undefined) return known
+    const entry = rebuild(session)
+    if (state.size >= MAX_TRACKED_SESSIONS) state.clear()
+    state.set(session.id, entry)
+    return entry
+  }
+  const predicate = (payload) => {
+    if (delegated !== undefined && isDelegated(sessionOf(payload)) !== delegated) return false
+    const count = countOf(entryOf(sessionOf(payload))) + (includeCurrent ? 1 : 0)
+    if (every !== undefined && (count === 0 || count % every !== 0)) return false
+    return (min === undefined || count >= min) && (max === undefined || count <= max)
+  }
+  predicate.kind = 'count'
+  predicate.observe = (session, event) => {
+    const entry = session?.id === undefined ? undefined : state.get(session.id)
+    if (entry !== undefined) applyEvent(entry, event)
+  }
+  return predicate
+}

package/engine/conditions/evaluation.mjs

@@ -0,0 +1,41 @@
+import { subjectOf } from './subject.mjs'
+
+/**
+ * 一次官方调用的局部判定帧；不按 session、turn 或载荷身份缓存。
+ * `ctx` 是判定期服务入口：子代理事件靠它用 `id` 反查 agent（见 subject.mjs 的
+ * `subagentFacts`），使 `modelScope`/`audience` 在判定阶段就有事实可用。
+ */
+export function ruleFrame(channel, args, warnOnce = () => {}, ctx) {
+  return { channel, args, subject: subjectOf(channel, args, warnOnce, ctx), decisions: new Map(), warnOnce }
+}
+
+export function ruleMatches(rule, frame) {
+  if (rule === undefined) return true
+  if (frame.decisions.has(rule)) return frame.decisions.get(rule)
+  let hit = rule.enabled !== false
+  if (hit && typeof rule.when === 'function') {
+    try { hit = rule.when(frame.subject) === true }
+    catch (error) { hit = false; frame.warnOnce(`rule ${rule.id} condition failed: ${String(error?.message ?? error)}`) }
+  }
+  frame.decisions.set(rule, hit)
+  return hit
+}
+
+/**
+ * 动作级判定：规则条件与动作自身的分支条件都要过。
+ *
+ * `bypassRuleWhen` 的动作来自规则级 `else`——它的条件里已经含 `not(if)`，再叠加
+ * `rule.when` 会自相矛盾、令该分支永不执行。动作条件缺省 = 恒真；非 `true`
+ * （含 UNAVAILABLE 三值语义）一律不命中，与 `ruleMatches` 同一纪律。
+ */
+export function actionMatches(entry, frame) {
+  if (entry.bypassRuleWhen !== true && !ruleMatches(entry.rule, frame)) return false
+  const when = entry.actionWhen
+  if (when === undefined) return true
+  try {
+    return when(frame.subject) === true
+  } catch (error) {
+    frame.warnOnce(`action ${entry.id} condition failed: ${String(error?.message ?? error)}`)
+    return false
+  }
+}

package/engine/conditions/examples.mjs

@@ -0,0 +1,11 @@
+export const PREDICATE_EXAMPLES = {
+  text: { subject: 'userMessage', keys: ['keyword'] },
+  phase: { promoted: false },
+  source: { kind: 'user' },
+  count: { of: 'tool-call', per: 'turn', min: 1 },
+  names: { allow: ['bash'] },
+  session: { type: 'user/message', present: false },
+  preset: { presetId: 'preset-id' },
+  scope: { audience: 'main', modelScope: 'all' },
+  anchor: { keys: ['We'], fallbackAfter: 1 },
+}