dsh-plugin-prompt-tool 0.3.1 → 0.4.0

package/preset/prompt-injector.mjs

@@ -1,127 +1,112 @@
-/**
- * prompt-injector — anchored-standard 的附加件（prompt-tool 自研，唯一本地件）。
- *
- * 职责（tools / maxTokens / 上下文剥离全部留给原版 tool-bootstrap）：
- *   会话晋升（首个 tool/call 或 assistant/message，与 promoteOn: either 同定义）后，
- *   turn1 reasoning 以 "we" 开头 → 下一轮注入 promptText 一次；
- *   we 未确认 → 最多再等一轮，仍无则强制注入（兜底，绝不卡死）。
- *
- * promptText 由宿主在生成 preset 时准备好：
- *   - 默认等于 preset.md 原文；
- *   - 开启 injectAgentsPrompt 时，宿主会把 AGENTS.md 拼接到 preset.md 头部。
- *   本模块只负责把最终文本作为一条 user 消息注入，不做路径探测。
- *
- * 实测依据：
- *   - 复杂任务 + 原版 2 工具 + maxTokens 1024 → turn1 reasoning "We need"；
- *   - 简单任务模型直接调工具干活（无 we 首词），走兜底注入；
- *   - 锚定消息（"Tools are not open yet"）在 2 工具下不产生 we
- *     （模型回复 "The user says..." 叙述语气），已废弃。
- *
- * 状态全部从持久 session events 推导（resume/reload 安全）：
- *   - promoted：events 含 tool/call 或 assistant/message；
- *   - 已注入：events 含 source.kind=plugin + source.plugin=prompt-injector 的
- *     消息事件（注入消息本身就是持久事件），进程重启/插件重载后据此跳过；
- *   - 内存 Set/Map 只做进程内快路径 memo，不承载跨进程真相。
- *   注入仅一次。
- */
-
-/** Cordis plugin name used by loader diagnostics. */
-export const name = 'prompt-injector'
-
-/** No inject list: nothing to resolve, only event listeners. */
-export const inject = []
-
-export function apply(ctx, config) {
-  const promptText = typeof config.promptText === 'string' && config.promptText.length > 0
-    ? config.promptText
-    : undefined
-
-  /** 消息 id：优先 crypto.randomUUID，旧运行时回退到随机串。 */
-  const newMessageId = () =>
-    typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-      ? crypto.randomUUID()
-      : `prompt-injector-${Date.now()}-${Math.random().toString(36).slice(2)}`
-
-  /** Sessions whose promptText has been injected (append-only). */
-  const injectedPrompt = new Set()
-  /** Sessions already promoted in this process (memoized). */
-  const promoted = new Set()
-  /** Sessions whose first assistant reasoning has been scanned (memoized). */
-  const weScanned = new Map()
-
-  /**
-   * 从持久 session events 推导「是否已经注入过 promptText」。
-   * 注入消息本身就是 user/message 持久事件（data 即消息本体），因此跨进程
-   * 重启 / 插件热重载后仍能识别；兼容 router-standard 观测到的
-   * `data.message` 嵌套形状。内存 Set 只做快路径 memo，真相在事件流。
-   */
-  const hasInjectedPrompt = (session) =>
-    session.events.some((event) => {
-      const payload = event.data && typeof event.data.message === 'object' && event.data.message !== null
-        ? event.data.message
-        : event.data
-      const source = payload?.source
-      return source?.kind === 'plugin' && source?.plugin === 'prompt-injector'
-    })
-
-  /** 与 tool-bootstrap 的 promoteOn: either 同定义。 */
-  const isPromoted = (agent) => {
-    if (agent === undefined) return true
-    const session = agent.session
-    if (session === undefined) return true
-    if ((session.header.delegationDepth ?? 0) > 0) return true
-    if (promoted.has(session.id)) return true
-    const hit = session.events.some((event) => event.type === 'tool/call' || event.type === 'assistant/message')
-    if (hit) promoted.add(session.id)
-    return hit
-  }
-
-  /** 第一个 assistant/message（锚定轮）的 reasoning 是否以 "we" 开头。 */
-  const isWeAnchored = (agent) => {
-    const session = agent.session
-    const cached = weScanned.get(session.id)
-    if (cached !== undefined) return cached
-    const first = session.events.find((event) => event.type === 'assistant/message')
-    // 首个 assistant 消息尚未落库时不要缓存 false，等待下一轮再查。
-    if (first === undefined) return false
-    const content = first.data?.message?.content ?? []
-    const reasoning = content.find((block) => block.type === 'reasoning')
-    const anchored = reasoning !== undefined && /^we\b/i.test(String(reasoning.text ?? '').trim())
-    weScanned.set(session.id, anchored)
-    return anchored
-  }
-
-  /** 已落库的 assistant 回合数（we 未确认时的兜底轮计数）。 */
-  const assistantRounds = (agent) =>
-    agent.session.events.filter((event) => event.type === 'assistant/message').length
-
-  // 锚定确认后注入一次 promptText（we 确认立即注入；未确认最多再等一轮）。
-  ctx.on('agent/pre-step', async ({ agent }, next) => {
-    const decision = await next()
-    if (decision.kind === 'reject') return decision
-    if (promptText === undefined) return decision
-    if (!isPromoted(agent)) return decision
-    const session = agent.session
-    if (session === undefined || injectedPrompt.has(session.id)) return decision
-    // 持久事件级幂等：进程重启/插件重载后，已注入消息仍在事件流里，据此跳过。
-    if (hasInjectedPrompt(session)) {
-      injectedPrompt.add(session.id)
-      return decision
-    }
-    const weOk = isWeAnchored(agent)
-    if (!weOk && assistantRounds(agent) <= 1) return decision
-    injectedPrompt.add(session.id)
-    const message = {
-      id: newMessageId(),
-      role: 'user',
-      content: [{ type: 'text', text: promptText }],
-      source: {
-        kind: 'plugin',
-        plugin: 'prompt-injector',
-        form: 'notice',
-        summary: weOk ? 'prompt-tool 提示词（we 锚定确认后注入）' : 'prompt-tool 提示词（we 未确认，兜底注入）',
-      },
-    }
-    return { ...decision, messages: [message, ...decision.messages] }
-  })
+/**
+ * prompt-injector — prompt-tool 的提示词注入层。
+ *
+ * 职责：会话晋升（首个 tool/call 或 assistant/message，与 promoteOn: either
+ * 同定义）后，turn1 reasoning 以 "we" 开头 → 下一轮注入 promptText 一次；
+ * we 未确认 → 最多再等一轮，仍无则强制注入（兜底，绝不卡死）。
+ *
+ * promptText 由宿主在生成 preset 时写入 config（默认等于 preset.md 原文）。
+ * AGENTS.md 的注入走 instruction-hint.mjs，不由本模块拼接。
+ *
+ * 实测依据：
+ *   - 复杂任务 + 原版 2 工具 + maxTokens 1024 → turn1 reasoning "We need"；
+ *   - 简单任务模型直接调工具干活（无 we 首词），走兜底注入；
+ *   - 锚定消息（"Tools are not open yet"）在 2 工具下不产生 we
+ *     （模型回复 "The user says..." 叙述语气），已废弃。
+ *
+ * 状态全部从持久 session events 推导（resume/reload 安全）：
+ *   - promoted：events 含 tool/call 或 assistant/message；
+ *   - 已注入：events 含 source.kind=plugin + source.plugin=prompt-injector 的
+ *     消息事件（注入消息本身就是持久事件），进程重启/插件重载后据此跳过；
+ *   - 内存 Set/Map 只做进程内快路径 memo，不承载跨进程真相。
+ *   注入仅一次。
+ */
+
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { newMessageId, PROMOTE_EVENTS } from './shared.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'prompt-injector'
+
+/** No inject list: nothing to resolve, only event listeners. */
+export const inject = []
+
+export function apply(ctx, config) {
+  const promptText = typeof config.promptText === 'string' && config.promptText.length > 0
+    ? config.promptText
+    : undefined
+
+  /** Sessions whose promptText has been injected (append-only). */
+  const injectedPrompt = new Set()
+  /** Sessions whose first assistant reasoning has been scanned (memoized). */
+  const weScanned = new Map()
+  /** Epoch-aware promotion, same definition as tool-bootstrap/context-gate. */
+  const promotion = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: false })
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  /**
+   * 从持久 session events 推导「是否已经注入过 promptText」。
+   * 注入消息本身就是 user/message 持久事件（data 即消息本体），因此跨进程
+   * 重启 / 插件热重载后仍能识别；兼容 router-standard 观测到的
+   * `data.message` 嵌套形状。内存 Set 只做快路径 memo，真相在事件流。
+   */
+  const hasInjectedPrompt = (session) =>
+    session.events.some((event) => {
+      const payload = event.data && typeof event.data.message === 'object' && event.data.message !== null
+        ? event.data.message
+        : event.data
+      const source = payload?.source
+      return source?.kind === 'plugin' && source?.plugin === 'prompt-injector'
+    })
+
+
+
+  /** 第一个 assistant/message（锚定轮）的 reasoning 是否以 "we" 开头。 */
+  const isWeAnchored = (agent) => {
+    const session = agent.session
+    const cached = weScanned.get(session.id)
+    if (cached !== undefined) return cached
+    const first = session.events.find((event) => event.type === 'assistant/message')
+    // 首个 assistant 消息尚未落库时不要缓存 false，等待下一轮再查。
+    if (first === undefined) return false
+    const content = first.data?.message?.content ?? []
+    const reasoning = content.find((block) => block.type === 'reasoning')
+    const anchored = reasoning !== undefined && /^we\b/i.test(String(reasoning.text ?? '').trim())
+    weScanned.set(session.id, anchored)
+    return anchored
+  }
+
+  /** 已落库的 assistant 回合数（we 未确认时的兜底轮计数）。 */
+  const assistantRounds = (agent) =>
+    agent.session.events.filter((event) => event.type === 'assistant/message').length
+
+  // 锚定确认后注入一次 promptText（we 确认立即注入；未确认最多再等一轮）。
+  ctx.on('agent/pre-step', async ({ agent }, next) => {
+    const decision = await next()
+    if (decision.kind === 'reject') return decision
+    if (agent === undefined || promptText === undefined) return decision
+    if (!promotion.status(agent).promoted) return decision
+    const session = agent.session
+    if (session === undefined || injectedPrompt.has(session.id)) return decision
+    // 持久事件级幂等：进程重启/插件重载后，已注入消息仍在事件流里，据此跳过。
+    if (hasInjectedPrompt(session)) {
+      injectedPrompt.add(session.id)
+      return decision
+    }
+    const weOk = isWeAnchored(agent)
+    if (!weOk && assistantRounds(agent) <= 1) return decision
+    injectedPrompt.add(session.id)
+    const message = {
+      id: newMessageId('prompt-injector'),
+      role: 'user',
+      content: [{ type: 'text', text: promptText }],
+      source: {
+        kind: 'plugin',
+        plugin: 'prompt-injector',
+        form: 'notice',
+        summary: weOk ? 'prompt-tool 提示词（we 锚定确认后注入）' : 'prompt-tool 提示词（we 未确认，兜底注入）',
+      },
+    }
+    return { ...decision, messages: [message, ...decision.messages] }
+  })
 }

package/preset/router-first-turn.mjs

@@ -1,70 +1,73 @@
-/**
- * router-first-turn — prompt-tool 本地附加件（最优组合）。
- *
- * 依据 dsh-router-standard 的 router-bootstrap 组装逻辑：
- *   - 只替换 persona 段，保留计划模式段与其他第三方 section；
- *   - 首轮隐藏 mnemon:* 自动注入段并清空 contexts，晋升后恢复；
- *   - 按主会话模型自动选择 persona：
- *       Pro  → 官方训练原句；
- *       Flash → dsh-router-standard 的 Flash 弱路由人设（build/fix 分类 +
- *               回顾锚 + 收敛锚 + 反跑题锚 + 先深想再产出）；
- *   - 子代理（委托深度 > 0）直接放行完整结果，保证 dsh-mnemon 等插件
- *     通过工具白名单要求的 mnemon_* 工具首轮可见。
- *
- * 工具目录裁剪仍由上游 tool-bootstrap 负责（首轮 = 真实 Minimal 工具对；
- * 晋升后 = resident 集），本模块不触碰 tools，避免两层过滤器冲突。
- */
-
-/** Cordis 插件名，供 loader 诊断使用。 */
-export const name = 'router-first-turn'
-
-/** 无服务依赖，只监听 system-prompt 组装。 */
-export const inject = []
-
-/** 官方 RL 训练原句（保持与 Minimal 预设逐字节一致）。 */
-const RL_PERSONA = 'You are a helpful software engineer assistant.'
-
-/** dsh-router-standard 的 Flash 弱路由人设（build/fix 分类 + 三锚 + 深想）。 */
-const FLASH_PERSONA = [
-  'You are a helpful assistant.',
-  'Before acting, decide the task type (build or fix) and adopt the matching style: build → hands-on production; fix → inspect-and-plan.',
-  'Before acting, briefly review what you have already done in this session and continue from where you left off; do not repeat completed steps. Do not run environment checks (echo, whoami, uname, node --version, date) or exhaustive grep/glob scans.',
-  'Think deeply first, then produce.',
-].join('\n')
-
-/** 是否为 persona 段：旧 persona 段由本模块替换。 */
-function isPersonaSection(section) {
-  if (section === null || typeof section !== 'object') return false
-  const name = String(section.name ?? '')
-  return name === 'persona' || /persona/i.test(name)
-}
-
-/** 首轮需要隐藏的 mnemon 自动注入段（晋升后恢复）。 */
-function isMnemonSection(section) {
-  if (section === null || typeof section !== 'object') return false
-  return String(section.name ?? '').startsWith('mnemon:')
-}
-
-export function apply(ctx) {
-  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
-    const assembled = await next()
-    const agent = context.agent
-    if (agent === undefined) return assembled
-    const session = agent.session
-    if (session === undefined) return assembled
-
-    // 子代理不裁剪任何 section/context：它与 dsh-mnemon 的工具白名单协作。
-    if ((session.header?.delegationDepth ?? 0) > 0) return assembled
-
-    const modelId = agent.options?.model
-    const persona = typeof modelId === 'string' && /flash/i.test(modelId) ? FLASH_PERSONA : RL_PERSONA
-
-    const sections = assembled.sections ?? []
-    const promoted = session.events.some((event) => event.type === 'tool/call')
-    const kept = sections.filter((section) => !isPersonaSection(section) && (promoted || !isMnemonSection(section)))
-    const routerSections = [...kept, { name: 'router-persona', text: persona, order: 0 }]
-    return promoted
-      ? { ...assembled, sections: routerSections }
-      : { ...assembled, sections: routerSections, contexts: [] }
-  })
-}
+/**
+ * router-first-turn — prompt-tool 本地附加件（最优组合）。
+ *
+ * 依据 dsh-router-standard 的 router-bootstrap 组装逻辑：
+ *   - 只替换 persona 段，保留计划模式段与其他第三方 section；
+ *   - 首轮隐藏 mnemon:* 自动注入段，晋升后恢复（contexts 由 context-gate 清空/恢复）；
+ *   - 按主会话模型自动选择 persona：
+ *       Pro  → 官方训练原句；
+ *       Flash → dsh-router-standard 的 Flash 弱路由人设（build/fix 分类 +
+ *               回顾锚 + 收敛锚 + 反跑题锚 + 先深想再产出）；
+ *   - 子代理（委托深度 > 0）直接放行完整结果，保证 dsh-mnemon 等插件
+ *     通过工具白名单要求的 mnemon_* 工具首轮可见。
+ *
+ * 工具目录裁剪仍由 tool-bootstrap 负责（首轮 = 真实 Minimal 工具对；晋升后
+ * 恢复完整目录或切换 PTC），本模块不触碰 tools，避免两层过滤器冲突。
+ */
+
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { isDelegated, isFlashModel, PROMOTE_EVENTS } from './shared.mjs'
+
+/** Cordis 插件名，供 loader 诊断使用。 */
+export const name = 'router-first-turn'
+
+/** 无服务依赖，只监听 system-prompt 组装。 */
+export const inject = []
+
+/** 官方 RL 训练原句（保持与 Minimal 预设逐字节一致）。 */
+const RL_PERSONA = 'You are a helpful software engineer assistant.'
+
+/** dsh-router-standard 的 Flash 弱路由人设（build/fix 分类 + 三锚 + 深想）。 */
+const FLASH_PERSONA = [
+  'You are a helpful assistant.',
+  'Before acting, decide the task type (build or fix) and adopt the matching style: build → hands-on production; fix → inspect-and-plan.',
+  'Before acting, briefly review what you have already done in this session and continue from where you left off; do not repeat completed steps. Do not run environment checks (echo, whoami, uname, node --version, date) or exhaustive grep/glob scans.',
+  'Think deeply first, then produce.',
+].join('\n')
+
+/** 是否为 persona 段：旧 persona 段由本模块替换。 */
+function isPersonaSection(section) {
+  if (section === null || typeof section !== 'object') return false
+  const name = String(section.name ?? '')
+  return name === 'persona' || /persona/i.test(name)
+}
+
+/** 首轮需要隐藏的 mnemon 自动注入段（晋升后恢复）。 */
+function isMnemonSection(section) {
+  if (section === null || typeof section !== 'object') return false
+  return String(section.name ?? '').startsWith('mnemon:')
+}
+
+export function apply(ctx) {
+  const promotion = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: false })
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
+    const assembled = await next()
+    const agent = context.agent
+    if (agent === undefined) return assembled
+    const session = agent.session
+    if (session === undefined) return assembled
+
+    // 子代理不裁剪任何 section/context：它与 dsh-mnemon 的工具白名单协作。
+    if (isDelegated(session)) return assembled
+
+    const persona = isFlashModel(agent.options?.model) ? FLASH_PERSONA : RL_PERSONA
+
+    const sections = assembled.sections ?? []
+    const promoted = promotion.status(agent).promoted
+    const kept = sections.filter((section) => !isPersonaSection(section) && (promoted || !isMnemonSection(section)))
+    // contexts 由 context-gate 统一清空/恢复，本模块只替换 persona 与隐藏 mnemon 段。
+    return { ...assembled, sections: [...kept, { name: 'router-persona', text: persona, order: 0 }] }
+  })
+}

package/preset/router-guide.mjs

@@ -11,10 +11,13 @@
  * 子代理不注入；首轮不注入（首句锚定由 near-anchor 负责）。
  */
 
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { extractText, isDelegated, isFlashModel, newMessageId, PROMOTE_EVENTS } from './shared.mjs'
+
 /** Cordis 插件名，供 loader 诊断使用。 */
 export const name = 'router-guide'
 
-/** 无服务依赖，只监听 pre-step 消息组装。 */
+/** 无服务依赖，只监听 session/event 与 pre-step。 */
 export const inject = []
 
 /** 复杂任务判定：长度或架构关键词。 */
@@ -23,26 +26,19 @@ const COMPLEX_RE = /(架构|重构|全面|详细|设计|系统|优化|分析|arc
 const GUIDE_WEAK = '\nRouter: classify this task (build or fix) now, then adopt the matching style — build: direct production; fix: inspect-first. Think deeply first, then commit and act.'
 const GUIDE_DEEP = '\nRouter: classify this task (build or fix) now, then adopt the matching style — build: direct production; fix: inspect-first. Think deeply about the architecture, edge cases, and integration points. Do not spend reasoning on the environment or tooling. Produce when your information is complete. End each reasoning block with a decision or an information need.'
 
-function newMessageId() {
-  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-    ? crypto.randomUUID()
-    : `router-guide-${Date.now()}-${Math.random().toString(36).slice(2)}`
-}
+/** 宿主 UI 写入的默认编辑框文本；未改动时等价自动模式。 */
+const DEFAULT_GUIDE_TEXT = ['简单任务自动引导：', GUIDE_WEAK.trim(), '', '复杂任务自动引导：', GUIDE_DEEP.trim()].join('\n')
+
 
-function extractText(message) {
-  if (!message) return ''
-  const content = Array.isArray(message.content) ? message.content : []
-  return content.map((block) => (typeof block === 'string' ? block : (block?.text ?? ''))).join(' ').trim()
-}
 
 export function apply(ctx, config) {
   const useCustom = config?.useCustom === true
   const customText = typeof config?.text === 'string' ? config.text : ''
   const enabled = config?.enabled !== false
-  // 与宿主写入的默认内容一致：打开自定义但未改动默认文本时，等价自动模式。
-  const DEFAULT_GUIDE_TEXT = ['简单任务自动引导：', GUIDE_WEAK.trim(), '', '复杂任务自动引导：', GUIDE_DEEP.trim()].join('\n')
   const unchangedDefault = customText.trim() === DEFAULT_GUIDE_TEXT.trim()
-  const effectiveAuto = !useCustom || unchangedDefault
+
+  const promotion = createEpochPromotion(PROMOTE_EVENTS.either, { includeSubagents: false })
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
 
   ctx.on('agent/pre-step', async ({ agent }, next) => {
     const decision = await next()
@@ -51,14 +47,12 @@ export function apply(ctx, config) {
     const session = agent.session
     if (session === undefined) return decision
     // 子代理不注入。
-    if ((session.header?.delegationDepth ?? 0) > 0) return decision
+    if (isDelegated(session)) return decision
     // 自动模式只对 Flash 主会话注入；自定义开关打开后，Pro 与 Flash 一样注入。
-    const modelId = agent.options?.model
-    const isFlash = typeof modelId === 'string' && /flash/i.test(modelId)
+    const isFlash = isFlashModel(agent.options?.model)
     if (!useCustom && !isFlash) return decision
     // 晋升后才注入（首轮由 near-anchor 负责）。
-    const promoted = session.events.some((event) => event.type === 'tool/call' || event.type === 'assistant/message')
-    if (!promoted) return decision
+    if (!promotion.status(agent).promoted) return decision
 
     const messages = Array.isArray(decision.messages) ? decision.messages : []
     const userIndex = messages.findIndex((message) => message?.source?.kind === 'user')
@@ -75,7 +69,7 @@ export function apply(ctx, config) {
 
     const nextMessages = [...messages]
     nextMessages.splice(userIndex + 1, 0, {
-      id: newMessageId(),
+      id: newMessageId('router-guide'),
       role: 'user',
       content: [{ type: 'text', text: guide }],
       source: { kind: 'router-guide', plugin: 'router-guide', form: 'notice', summary: 'router-guide 每轮近距离引导' },

package/preset/shared.mjs

@@ -0,0 +1,83 @@
+/**
+ * shared — small utilities shared by the prompt-tool preset scripts.
+ * Not a plugin row: no name/inject exports and no listeners.
+ */
+
+/** Durable session event types that count as a promotion signal per mode. */
+export const PROMOTE_EVENTS = {
+  'tool-call': ['tool/call'],
+  'assistant-message': ['assistant/message'],
+  either: ['tool/call', 'assistant/message'],
+}
+
+/** Parse the shared promoteOn vocabulary. */
+export function parsePromoteOn(pluginName, value) {
+  if (value === undefined || value === 'either') return PROMOTE_EVENTS.either
+  if (value === 'tool-call' || value === 'assistant-message') return PROMOTE_EVENTS[value]
+  throw new TypeError(`${pluginName}: promoteOn must be one of "tool-call", "assistant-message", "either"; got ${JSON.stringify(value)}`)
+}
+
+/** Validate an optional boolean config flag with a default. */
+export function booleanOption(pluginName, value, field, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${pluginName}: ${field} must be a boolean`)
+  }
+  return value
+}
+
+/** Validate the shared config envelope and unknown-key contract. */
+export function validateConfig(pluginName, source, allowedKeys) {
+  const config = source === undefined ? {} : source
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+    throw new TypeError(`${pluginName}: config must be an object`)
+  }
+  const unknown = Object.keys(config).filter((key) => !allowedKeys.has(key))
+  if (unknown.length > 0) {
+    throw new TypeError(
+      `${pluginName}: unknown config key(s) ${unknown.join(', ')} — allowed keys: ${[...allowedKeys].sort().join(', ')}`,
+    )
+  }
+  return config
+}
+
+/** One-shot logger guard shared by filters that degrade instead of throwing. */
+export function createWarnOnce(ctx, pluginName) {
+  let warned = false
+  return (message) => {
+    if (warned) return
+    warned = true
+    try {
+      ctx.logger.warn(message)
+    } catch {
+      // Logger unavailable — the guard exists only to avoid spamming.
+    }
+  }
+}
+
+/** Random message id with a crypto.randomUUID fast path. */
+export function newMessageId(prefix) {
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+/** Extract plain text from a message or from a wrapped event data shape. */
+export function extractText(message) {
+  if (!message) return ''
+  const payload = message && typeof message.message === 'object' && message.message !== null
+    ? message.message
+    : message
+  const content = Array.isArray(payload.content) ? payload.content : []
+  return content.map((block) => (typeof block === 'string' ? block : (block?.text ?? ''))).join(' ').trim()
+}
+
+/** True for subagent sessions. */
+export function isDelegated(session) {
+  return (session?.header?.delegationDepth ?? 0) > 0
+}
+
+/** True when a model id looks like a Flash-family model. */
+export function isFlashModel(modelId) {
+  return typeof modelId === 'string' && /flash/i.test(modelId)
+}