dsh-plugin-prompt-tool 1.0.0 → 2.0.0

package/engine/conditions/index.mjs

@@ -0,0 +1,85 @@
+import { createTextPredicate } from './text.mjs'
+import { createPhasePredicate } from './phase.mjs'
+import { createSourcePredicate } from './source.mjs'
+import { createCountPredicate } from './count.mjs'
+import { createNameListPredicate } from './names.mjs'
+import { createSessionStatePredicate } from './session.mjs'
+import { createPresetPredicate } from './preset.mjs'
+import { createScopePredicate } from './scope.mjs'
+import { createAnchorPredicate } from './anchor.mjs'
+import { withAvailableInput } from './availability.mjs'
+import { composite } from './composite.mjs'
+export * from './text.mjs'
+export * from './phase.mjs'
+export * from './source.mjs'
+export * from './count.mjs'
+export * from './names.mjs'
+export * from './session.mjs'
+export * from './preset.mjs'
+export * from './scope.mjs'
+export * from './anchor.mjs'
+export { subjectOf } from './subject.mjs'
+export { composite } from './composite.mjs'
+export const PREDICATE_FACTORIES = Object.freeze({
+  text: createTextPredicate,
+  phase: createPhasePredicate,
+  source: createSourcePredicate,
+  count: createCountPredicate,
+  names: createNameListPredicate,
+  session: createSessionStatePredicate,
+  preset: createPresetPredicate,
+  scope: createScopePredicate,
+  anchor: createAnchorPredicate,
+})
+export const COMPOSITE_OPERATORS = Object.freeze(['any', 'all', 'not', 'notAny'])
+
+const objectOrUndefined = (value, label) => {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`trigger-spec: ${label} must be an object`)
+  }
+  return value
+}
+
+export function compileWhen(node, context = {}) {
+  if (node === undefined || node === null) return undefined
+  if (typeof node !== 'object' || Array.isArray(node)) {
+    throw new TypeError('trigger-spec: when must be an object (a composite node or a predicate node)')
+  }
+  const keys = Object.keys(node)
+  if (keys.length === 0) {
+    throw new TypeError('trigger-spec: when must not be an empty object — 空节点是「恒真」还是「写漏了」无法区分')
+  }
+  if (keys.length > 1) {
+    throw new TypeError(
+      `trigger-spec: when must declare exactly one key — got ${keys.sort().join(', ')}`
+      + `（allowed: ${[...COMPOSITE_OPERATORS, ...Object.keys(PREDICATE_FACTORIES)].sort().join(', ')}）`,
+    )
+  }
+  const [key] = keys
+  const value = node[key]
+
+  if (COMPOSITE_OPERATORS.includes(key)) {
+    if (key === 'not') {
+      return composite({ not: compileWhen(value, context) })
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new TypeError(`trigger-spec: when.${key} must be a non-empty array of nodes`)
+    }
+    return composite({ [key]: value.map((child) => compileWhen(child, context)) })
+  }
+
+  const factory = PREDICATE_FACTORIES[key]
+  if (factory === undefined) {
+    throw new TypeError(
+      `trigger-spec: unknown predicate ${JSON.stringify(key)}`
+      + ` — known predicates: ${Object.keys(PREDICATE_FACTORIES).join(', ')}; composite: ${COMPOSITE_OPERATORS.join(', ')}`,
+    )
+  }
+  const options = objectOrUndefined(value, `when.${key}`) ?? {}
+  // `preset` 原语的取法需要挂载期注入（见 predicates.mjs 的三条硬约束），其余原语只用选项。
+  if (key === 'preset') {
+    return withAvailableInput(key, options, createPresetPredicate({ ...options, ctx: context.ctx, standingMountFor: context.standingMountFor }))
+  }
+  return withAvailableInput(key, options, factory(options))
+}

package/engine/conditions/names.mjs

@@ -0,0 +1,21 @@
+import { nameList, optionalBoolean } from './values.mjs'
+import { conditionInputAvailable, UNAVAILABLE } from './availability.mjs'
+
+export function createNameListPredicate(options = {}) {
+  const allow = nameList(options.allow, 'allow')
+  const deny = nameList(options.deny, 'deny')
+  const caseSensitive = optionalBoolean(options.caseSensitive, 'caseSensitive', true)
+  const normalize = (name) => (caseSensitive ? name : name.toLowerCase())
+  const allowSet = allow === undefined ? undefined : new Set(allow.map(normalize))
+  const denySet = deny === undefined ? undefined : new Set(deny.map(normalize))
+  const predicate = (payload) => {
+    if (!conditionInputAvailable('names', options, payload)) return UNAVAILABLE
+    const name = typeof payload === 'string' ? payload : payload?.name
+    const value = normalize(name)
+    if (denySet !== undefined && denySet.has(value)) return false
+    if (allowSet !== undefined && !allowSet.has(value)) return false
+    return true
+  }
+  predicate.kind = 'names'
+  return predicate
+}

package/engine/conditions/phase.mjs

@@ -0,0 +1,54 @@
+import { createEpochPromotion } from '../compaction-epoch.mjs'
+import { parsePromoteOn } from '../shared.mjs'
+import { agentOf } from './subject.mjs'
+import { optionalBoolean } from './values.mjs'
+
+export function createPhasePredicate(options = {}) {
+  const promoteEvents = options.promoteEvents ?? parsePromoteOn('predicates', options.promoteOn)
+  if (!Array.isArray(promoteEvents) || promoteEvents.some((type) => typeof type !== 'string')) {
+    throw new TypeError('predicates: promoteEvents must be an array of event type strings')
+  }
+  const subscribe = optionalBoolean(options.subscribe, 'subscribe', true)
+  const trackerOptions = {
+    includeSubagents: options.includeSubagents === true,
+    promoteGate: options.promoteGate === true,
+    promoteAfterFirstResponse: options.promoteAfterFirstResponse === true,
+    maxPromoteSteps: options.maxPromoteSteps,
+    reasoningPattern: options.reasoningPattern,
+    reasoningNegativePattern: options.reasoningNegativePattern,
+    reasoningFlags: options.reasoningFlags,
+  }
+  const tracker = createEpochPromotion(promoteEvents, trackerOptions)
+  // 载荷归一后 agent 在 `payload.agent`；旧的手工形态（载荷本身就是 agent）由 agentOf 兼容。
+  //
+  // `compacted`（2026-09-22 用户拍板「扩原语」）：`status()` 本来就返回 `boundary`
+  // （最近一次成功 `compaction/end` 的 seq，未压缩过为 -1），此前只用了 `promoted`。
+  // `compacted: true` = 发生过成功压缩；`false` = 从未压缩；未声明 = 不判该维度。
+  const compacted = optionalBoolean(options.compacted, 'compacted', undefined)
+  // `promoted` 三态：缺省 `true`（= 原行为，向后兼容）/ `false` / `'ignore'`。
+  //
+  // 为什么需要它（对拍实测）：原实现把 `compacted` 与 `promoted` 写成**合取**，于是可表达的
+  // 原子只有 `P`、`C∧P`、`¬C∧P`——三者在 **¬P 的会话上全为 false**，用 `any`/`all`/`not`/
+  // `notAny` 的任何组合都表达不出原 `tool-bootstrap` compaction 回退要的 **`C ∧ ¬P`**
+  // （受控相位 + 已压缩：压缩后回到受控工具集；声明侧见
+  // `test/engine/declarations/tool-bootstrap.yml` 声明 2）。解耦后
+  // `{ compacted: true, promoted: false }` 就是 `C ∧ ¬P`。
+  const promotedOption = options.promoted
+  if (promotedOption !== undefined && promotedOption !== true && promotedOption !== false && promotedOption !== 'ignore') {
+    throw new TypeError("predicates: phase promoted must be true, false or 'ignore'")
+  }
+  if (promotedOption === 'ignore' && compacted === undefined) {
+    throw new TypeError("predicates: phase promoted 'ignore' needs compacted — 否则该判定恒真")
+  }
+  const predicate = (payload) => {
+    const status = (subscribe ? tracker : createEpochPromotion(promoteEvents, trackerOptions))
+      .status(agentOf(payload))
+    if (compacted !== undefined && (status.boundary >= 0) !== compacted) return false
+    if (promotedOption === 'ignore') return true
+    return status.promoted === (promotedOption ?? true)
+  }
+  predicate.kind = 'phase'
+  // 只有订阅模式才有增量入口：不订阅时多一个入口只会诱使调用方以为状态被记住了。
+  if (subscribe) predicate.observe = (session, event) => tracker.observe(session, event)
+  return predicate
+}

package/engine/conditions/preset.mjs

@@ -0,0 +1,94 @@
+import { importHostPackage } from '../host-package.mjs'
+import { getService } from '../shared.mjs'
+import { agentOf } from './subject.mjs'
+import { UNAVAILABLE } from './availability.mjs'
+
+const AGENT_PRESETS_PACKAGE = '@deepseek-ai/dsh-agent-preset-registry'
+
+/**
+ * 当前预设 id（进程内判定；官方唯一正确取法）。
+ *
+ *     const id = ctx.get?.('agentPresets')?.composedPreset?.(agent.ctx)   // 首选
+ *       ?? standingMountFor(agent.ctx)?.presetId                          // 服务未就绪时的同源兜底
+ *
+ * 依据：官方 0.1.7 的 `agent-preset-registry/src/index.ts` 中 composedPreset
+ * 直接包装 `standingMountFor(agentCtx)?.presetId`；mount.ts 读取 live scope chain，
+ * invariant.ts 也以该结果判定 agent 是否已绑定预设，不依赖事件落盘。
+ *
+ * 三条硬约束（改这里之前先读 PLAN 的「审查结论」）：
+ *  1. **禁止读 `session.header.agentPreset`**——它是出生预设。官方 `agent-preset-registry/src/session.ts`
+ *     明写「Reconstruction reads the `agentPreset` Session projection, never the header alone」，
+ *     投影初值取自 header、之后由 `agent-preset/selected` 推进；真机实测亦有 header 与
+ *     实际挂载不一致的案例。
+ *  2. **禁止用 registry 的 defaultId** 当当前预设——它是
+ *     **新会话的默认值**，与任何已存在 agent 的挂载无关。
+ *  3. **`undefined` 的含义是「该 agent 没有预设」**（裸 agent），不是「取不到」；
+ *     **不得回退到默认值**，调用方按「不干预 / 不命中」处理。
+ *
+ * 适用边界：`composedPreset` 只在**进程内、拿得到 `agent.ctx`** 时可用（装配期
+ * `context.agent.ctx`、子代理认领、引擎能力）。跨 API/客户端边界没有这个方法——
+ * 官方 `ctx.remote.agentPresets` 提供 `list / select` 等远程操作，
+ * 客户端拿不到 `agent.ctx` 也无法用本方法。**两种取法是分工而非替代**：
+ * 进程内判定用本函数，跨边界用会话投影（`sessionProjections.stateOf(session, 'agentPreset')`）。
+ *
+ * @param {object|undefined} ctx 插件/运行时 ctx（服务查询基准）
+ * @param {{ctx?: unknown}|undefined} agent 判定对象（读它的 `ctx` = agent scope context）
+ * @param {Function} [standingMountFor] 官方模块导出兜底（服务未就绪时用）
+ * @returns {string|undefined} 预设 id；`undefined` = 该 agent 没有预设
+ */
+export function agentPresetId(ctx, agent, standingMountFor) {
+  try {
+    const service = getService(ctx, 'agentPresets')
+    const composed = typeof service?.composedPreset === 'function'
+      ? service.composedPreset(agent?.ctx)
+      : undefined
+    if (composed !== undefined && composed !== null) return composed
+    const mount = typeof standingMountFor === 'function' ? standingMountFor(agent?.ctx) : undefined
+    return mount?.presetId
+  } catch {
+    // 判定不抛出：拿不到就是「没有预设」（不命中），与 condition.mjs 的降级纪律一致。
+    return undefined
+  }
+}
+
+/**
+ * 惰性解析官方 `standingMountFor`（挂载期一次，判定期零 IO）。
+ * 官方包缺席（最小组合、测试环境）＝没有兜底，不是错误：此时服务缺席即判定恒 undefined。
+ * @param {string} [entry] 解析基准（缺省按宿主入口解析；测试/嵌入可显式指定）
+ * @returns {Promise<Function|undefined>}
+ */
+export async function loadStandingMountFor(entry) {
+  try {
+    const module = await importHostPackage(AGENT_PRESETS_PACKAGE, entry)
+    return typeof module?.standingMountFor === 'function' ? module.standingMountFor : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 当前预设判断：`agentPresetId(...) === presetId`。
+ *
+ * `ctx` 在**构造期**绑定（服务查询基准，通常是触发器运行时的插件 ctx）；
+ * 判定只读 payload（agent）。无可确定的当前预设事实时保持 UNAVAILABLE，not 也不能放行。
+ *
+ * @param {object} options
+ * @param {string} options.presetId 目标预设 id
+ * @param {object} [options.ctx] 插件/运行时 ctx
+ * @param {Function} [options.standingMountFor] 官方模块导出兜底
+ * @returns {(agent: unknown) => boolean|symbol}
+ */
+export function createPresetPredicate(options = {}) {
+  const presetId = options.presetId
+  if (typeof presetId !== 'string' || presetId.length === 0) {
+    throw new TypeError('predicates: a preset predicate needs a presetId')
+  }
+  const ctx = options.ctx
+  const standingMountFor = options.standingMountFor
+  const predicate = (payload) => {
+    const current = agentPresetId(ctx, agentOf(payload), standingMountFor)
+    return typeof current === 'string' && current.length > 0 ? current === presetId : UNAVAILABLE
+  }
+  predicate.kind = 'preset'
+  return predicate
+}

package/engine/conditions/scope.mjs

@@ -0,0 +1,18 @@
+import { isDelegated, matchesModel } from '../shared.mjs'
+import { agentOf } from './subject.mjs'
+
+export function createScopePredicate(options = {}) {
+  if (options.audience !== undefined && !['main', 'subagent'].includes(options.audience)) throw new TypeError('scope.audience must be main or subagent')
+  if (options.modelScope !== undefined && !['all', 'pro', 'flash'].includes(options.modelScope)) throw new TypeError('scope.modelScope must be all, pro or flash')
+  const predicate = payload => {
+    const agent = agentOf(payload)
+    const session = payload?.session ?? agent?.session
+    if (options.audience !== undefined) {
+      if (session === undefined) return false
+      if ((options.audience === 'subagent') !== isDelegated(session)) return false
+    }
+    return matchesModel(options.modelScope ?? 'all', payload?.model ?? agent?.options?.model)
+  }
+  predicate.kind = 'scope'
+  return predicate
+}

package/engine/conditions/session.mjs

@@ -0,0 +1,22 @@
+import { isDelegated, sessionEvents } from '../shared.mjs'
+import { sessionOf } from './subject.mjs'
+import { optionalBoolean } from './values.mjs'
+
+export function createSessionStatePredicate(options = {}) {
+  const type = options.type
+  if (typeof type !== 'string' || type.length === 0) {
+    throw new TypeError('predicates: a session-state predicate needs an event type')
+  }
+  const present = optionalBoolean(options.present, 'present', false)
+  // 受众判据（2026-09-22 用户拍板「扩原语」）：`delegated: false` = 只在主会话命中，
+  // `true` = 只在子代理命中，未声明 = 不判受众。子代理判定复用 `shared.isDelegated`，
+  // 不写字面量比较（trigger.mjs 的会话态契约第 (2) 条纪律）。
+  const delegated = optionalBoolean(options.delegated, 'delegated', undefined)
+  const predicate = (payload) => {
+    if (delegated !== undefined && isDelegated(sessionOf(payload)) !== delegated) return false
+    return sessionEvents(sessionOf(payload))
+      .some((event) => event?.type === type) === present
+  }
+  predicate.kind = 'session'
+  return predicate
+}

package/engine/conditions/source.mjs

@@ -0,0 +1,63 @@
+import { optionalBoolean } from './values.mjs'
+import { conditionInputAvailable, UNAVAILABLE } from './availability.mjs'
+
+function sourceChannel(value, field) {
+  if (value === undefined) return undefined
+  if (typeof value === 'string' && value.length > 0) return [value]
+  if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string' && item.length > 0)) {
+    return [...new Set(value)]
+  }
+  throw new TypeError(`predicates: ${field} must be a non-empty string or an array of non-empty strings`)
+}
+
+/**
+ * 来源判断：`source.kind` / `source.plugin` 的比较（context-gate 的 allowKinds 一族
+ * 与 executor 的双通道去重都是这套比较）。
+ *
+ *  - **精确**（缺省）为 `===` 语义，且**大小写敏感**——现有四处调用
+ *    （context-gate / executor / anchor-turn / instruction-hint）全是精确且区分大小写，
+ *    统一不得放宽；大小写不敏感必须显式 `caseSensitive: false`。
+ *  - **前缀**仅在 `match: 'prefix'` 时启用。
+ *  - 声明了多个通道时是**合取**（都命中才算命中）；需要析取用
+ *    `composite({ any: [source({kind}), source({plugin})] })`——不隐式二选一。
+ *
+ * @param {object} options
+ * @param {string|string[]} [options.kind]
+ * @param {string|string[]} [options.plugin]
+ * @param {boolean} [options.caseSensitive] 缺省 true
+ * @param {'exact'|'prefix'} [options.match] 缺省 exact
+ * @returns {(payload: unknown) => boolean}
+ */
+export function createSourcePredicate(options = {}) {
+  const kinds = sourceChannel(options.kind, 'kind')
+  const plugins = sourceChannel(options.plugin, 'plugin')
+  if (kinds === undefined && plugins === undefined) {
+    throw new TypeError('predicates: a source predicate needs kind or plugin')
+  }
+  const caseSensitive = optionalBoolean(options.caseSensitive, 'caseSensitive', true)
+  const match = options.match ?? 'exact'
+  if (match !== 'exact' && match !== 'prefix') {
+    throw new TypeError('predicates: source match must be "exact" or "prefix"')
+  }
+  const normalize = (value) => (caseSensitive ? value : value.toLowerCase())
+  const asSet = (list) => (list === undefined ? undefined : new Set(list.map(normalize)))
+  const kindSet = asSet(kinds)
+  const pluginSet = asSet(plugins)
+  const channelHit = (value, allowed) => {
+    if (allowed === undefined) return true
+    if (typeof value !== 'string' || value.length === 0) return false
+    const normalized = normalize(value)
+    if (match === 'exact') return allowed.has(normalized)
+    for (const prefix of allowed) {
+      if (normalized.startsWith(prefix)) return true
+    }
+    return false
+  }
+  const predicate = (payload) => {
+    if (!conditionInputAvailable('source', options, payload)) return UNAVAILABLE
+    const source = payload?.source
+    return channelHit(source?.kind, kindSet) && channelHit(source?.plugin, pluginSet)
+  }
+  predicate.kind = 'source'
+  return predicate
+}

package/engine/conditions/subject.mjs

@@ -0,0 +1,121 @@
+import { lastAssistantText, subagentTextOf, toolArgsText, userMessagesText } from '../condition.mjs'
+import { extractText } from '../shared.mjs'
+
+const CHANNEL_SUBJECTS = {
+  'system-prompt/assemble': (args) => ({ agent: args[1]?.agent }),
+  'agent/request': (args) => ({ agent: args[0]?.agent }),
+  'agent/pre-step': (args) => ({ agent: args[0]?.agent }),
+  'agent/inbox/inserted': (args) => ({ agent: args[0]?.agent, source: args[0]?.message?.source }),
+  'agent/turn-stopping': (args) => ({ agent: args[0]?.agent }),
+  'tools/pre-execute': (args) => ({ agent: args[0]?.agent, name: args[0]?.name }),
+  'tools/post-execute': (args) => ({ agent: args[0]?.agent, name: args[0]?.name }),
+  'session/event': (args) => ({ session: args[0] }),
+  'llm/stream': (args) => ({ model: args[0]?.model }),
+  'subagent/start': () => ({}),
+  'subagent/end': () => ({}),
+}
+
+/** 未知通道的告警去重（每个通道一次；判定期不刷屏）。 */
+const warnedChannels = new Set()
+
+/**
+ * 归一化载荷的标记（Symbol，非字符串键）：`subjectOf` 产出它，`agentOf`/`sessionOf` 据此
+ * 区分「归一化载荷」与「旧形态的直接 payload」——**不用启发式猜**（曾按「有没有 `.session`」
+ * 判断，结果把测试里 `{ id, ctx }` 形状的假 agent 误判成归一化载荷）。
+ */
+const SUBJECT_MARK = Symbol('predicate-subject')
+
+/**
+ * 子代理事件判定期可见的 agent 事实。
+ *
+ * 官方 `subagent/start`、`subagent/end` 的载荷只有 `runId/provider/id/local`；
+ * `wireSubagentEvents` 是在 handler 里才把 child 挂上 frame 的，而 `ruleMatches`
+ * 在 handler **之前**执行。结果是 `scope.modelScope`（availability 要求 model 为非空
+ * 字符串）与 `scope.audience`（要求 session 可达）在子代理两层恒判 UNAVAILABLE——UI 上
+ * 配了却永远不命中，正是 schema 注释要避免的「配了没效果也不报错」。
+ *
+ * 这里在**判定前**用事件里的 `id` 反查 agent 补齐同样的事实。取不到时不写键：判定
+ * 退回 UNAVAILABLE（fail-closed），不得乐观放行。
+ */
+function subagentFacts(info, ctx) {
+  const facts = {}
+  const id = info?.id
+  if (typeof id !== 'string' || id.length === 0) return facts
+  const agent = ctx?.agents?.get?.(id)
+  if (agent === undefined || agent === null) return facts
+  facts.agent = agent
+  if (agent.session !== undefined) facts.session = agent.session
+  const model = agent.options?.model
+  if (typeof model === 'string' && model.length > 0) facts.model = model
+  return facts
+}
+
+/**
+ * 把事件参数表归一为谓词载荷。
+ *
+ * `args` 传的是**去掉 `next` 之后的参数表**（无 `next` 的 emit/serial 通道原样传）。
+ * 未知通道回落到「第一个实参」（= 归一化之前的旧行为）并**告警一次**——不静默丢弃，
+ * 否则新增通道会悄悄失去判定能力；也不抛错，判定期抛错会打断会话。
+ *
+ * @param {string} channel 事件名
+ * @param {unknown[]} args 去掉 next 的参数表
+ * @param {Function} [warn] 告警回调（缺省静默）
+ * @param {unknown} [ctx] 判定期服务入口（目前只被子代理事件的 agent 反查使用）
+ * @returns {unknown} 谓词载荷
+ */
+export function subjectOf(channel, args, warn, ctx) {
+  // 第一个实参的字段**原样保留**在载荷顶层：旧形态（如 `agent/turn-stopping` 的
+  // `{ agent, turn }`）因此继续可见，既有断言不会因归一化而失效。
+  const first = args[0]
+  const base = first !== null && typeof first === 'object' && !Array.isArray(first) ? { ...first } : {}
+  const pick = CHANNEL_SUBJECTS[channel]
+  const text = (() => {
+    switch (channel) {
+      case 'tools/pre-execute': return { argsText: toolArgsText(args[0]?.arguments) }
+      case 'tools/post-execute': return { argsText: toolArgsText(args[0]?.arguments), resultText: extractText(args[1]) }
+      case 'agent/pre-step': return { userText: userMessagesText(args[0]?.messages) }
+      case 'agent/inbox/inserted': return { userText: userMessagesText([args[0]?.message]) }
+      case 'agent/turn-stopping': return { assistantText: lastAssistantText(args[0]?.agent?.session) }
+      // 子代理事件的 `name` = provider（`SubagentRunInfo` 里唯一稳定的分类事实：
+      // spawn / fork / acp / codex / claude-code / dsh-sdk）。`names` 谓词读的就是
+      // `payload.name`，因此 `when: { names: { allow: ['fork'] } }` 在此可用。
+      // provider 可能缺席（官方注释：已接受的 one-shot 变 ready 或持久 Activation 冷恢复时
+      // 提供方未必仍注册）——那时不写键，让 `names` 走 UNAVAILABLE，而不是塞空串当「已知为空」。
+      case 'subagent/start':
+      case 'subagent/end': return {
+        subagentText: subagentTextOf(args[0]),
+        ...(typeof args[0]?.provider === 'string' && args[0].provider.length > 0 ? { name: args[0].provider } : {}),
+        ...subagentFacts(args[0], ctx),
+      }
+      default: return {}
+    }
+  })()
+  if (pick === undefined) {
+    if (typeof warn === 'function' && !warnedChannels.has(channel)) {
+      warnedChannels.add(channel)
+      warn(`predicates: unknown channel ${JSON.stringify(channel)} — 无显式取法，退回「第一个实参即载荷」的旧语义`)
+    }
+    return { ...base, ...text, [SUBJECT_MARK]: true, channel, args }
+  }
+  return { ...base, ...pick(args), ...text, [SUBJECT_MARK]: true, channel, args }
+}
+
+/**
+ * 从载荷取 agent：**归一化载荷**读 `agent`（`subjectOf` 的标记为凭）；**旧形态**
+ * （载荷本身就是 agent——手写调用方与既有测试都这样传）原样返回。
+ */
+export function agentOf(payload) {
+  if (payload === null || typeof payload !== 'object') return undefined
+  return payload[SUBJECT_MARK] === true ? payload.agent : payload
+}
+
+/**
+ * 从载荷取 session：归一化载荷走 `session` → `agent.session`；旧形态走
+ * `session` → 载荷自身。取不到时返回原载荷——`sessionEvents` 对无 `snapshotEvents`
+ * 的对象返回空，语义是「无事件」，与归一化之前逐例一致。
+ */
+export function sessionOf(payload) {
+  if (payload === null || typeof payload !== 'object') return payload
+  if (payload[SUBJECT_MARK] !== true) return payload.session ?? payload
+  return payload.session ?? payload.agent?.session
+}

package/engine/conditions/text.mjs

@@ -0,0 +1,44 @@
+import { MATCH_LOGIC, createAnchorMatcher } from '../anchor-match.mjs'
+import { subjectTextOf } from '../condition.mjs'
+import { keyList } from './values.mjs'
+import { conditionInputAvailable, UNAVAILABLE } from './availability.mjs'
+const MATCH_FLAGS = ['caseSensitive', 'wholeWords', 'useRegex', 'stWords']
+const MATCH_MODES = ['scan', 'prefix']
+
+export function createTextPredicate(options = {}) {
+  const keys = keyList(options.keys, 'keys')
+  const secondaryKeys = keyList(options.secondaryKeys, 'secondaryKeys')
+  if (keys.length === 0 && secondaryKeys.length === 0) {
+    throw new TypeError('predicates: a text predicate needs at least one non-empty key')
+  }
+  const logic = options.logic ?? MATCH_LOGIC.ANY
+  if (!Object.values(MATCH_LOGIC).includes(logic)) {
+    throw new TypeError(`predicates: logic must be one of ${Object.values(MATCH_LOGIC).join(', ')}`)
+  }
+  const mode = options.mode ?? 'scan'
+  if (!MATCH_MODES.includes(mode)) {
+    throw new TypeError(`predicates: mode must be one of ${MATCH_MODES.join(', ')}`)
+  }
+  for (const field of MATCH_FLAGS) {
+    if (options[field] !== undefined && typeof options[field] !== 'boolean') {
+      throw new TypeError(`predicates: ${field} must be a boolean when present`)
+    }
+  }
+  // 与 anchor-match 逐例等价的关键：匹配器就是 anchor-match 的匹配器，本层不加也不减语义。
+  const matcher = createAnchorMatcher({
+    keys,
+    secondaryKeys,
+    caseSensitive: options.caseSensitive === true,
+    wholeWords: options.wholeWords === true,
+    useRegex: options.useRegex,
+    logic,
+    mode,
+    stWords: options.stWords === true,
+  })
+  const subject = options.subject
+  const predicate = (payload) => conditionInputAvailable('text', options, payload)
+    ? matcher.scan(typeof payload === 'string' ? payload : subjectTextOf(subject, payload)).active === true
+    : UNAVAILABLE
+  predicate.kind = 'text'
+  return predicate
+}

package/engine/conditions/values.mjs

@@ -0,0 +1,32 @@
+export function optionalBoolean(value, field, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') throw new TypeError(`predicates: ${field} must be a boolean`)
+  return value
+}
+
+/** 键集合归一化：非字符串数组 / 非数组一律 fail loud；空白键丢弃。 */
+export function keyList(value, field) {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new TypeError(`predicates: ${field} must be an array of strings when present`)
+  }
+  return value.map((item) => item.trim()).filter((item) => item.length > 0)
+}
+
+/** 名称集合：与 tool-filter 的 nameSet 同严格度（空串不是合法名称）。 */
+export function nameList(value, field) {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    throw new TypeError(`predicates: ${field} must be an array of non-empty strings`)
+  }
+  return [...new Set(value)]
+}
+
+/** 计数上下限：缺省 = 不设该侧；非安全非负整数一律 fail loud。 */
+export function boundOf(value, field) {
+  if (value === undefined) return undefined
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`predicates: count ${field} must be an integer >= 0`)
+  }
+  return value
+}