dsh-plugin-prompt-tool 0.8.1 → 2.0.0

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 },
+}

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
+}