dsh-plugin-prompt-tool 3.0.1 → 3.1.0

package/README.md

@@ -67,6 +67,8 @@ rules:
 
 规则是唯一行为源；共享模型与能力参数保存于 layerSettings，人设、变量与自定义工具各有独立顶层段。根 [module.yml](module.yml) 从权威目录生成九层及27个共享参数参考，示例默认关闭。
 
+单个模块装配失败时，首次加载跳过它，更新时恢复它的上次有效贡献；其他正常模块继续加载和更新。晚到服务的初始化失败也按此处理，等待中的新版本不会覆盖最后成功版本。故障仍会报告，修正该模块定义或显式刷新后重试。全局配置和跨模块独占冲突仍明确拒绝，不自动选择赢家；完整边界见[运行时装配](docs/engine-reuse.md)。
+
 - 条件使用 if，动作用 then，另有 else；动作身份在完整规则树中唯一。
 - 注入正文策略为 static、placeholder、context-activation；文本与长度分类、确认、工具名和受众由通用条件承担，正文、投递、请求与流控制由动作组合。
 - 工具提示通过 tool-catalog 只读引用同规则工具可见面声明，自动列出常驻名单与发现工具；提示正文和投递由模块规则控制。
@@ -110,6 +112,8 @@ persona:
 | module-file-tools | module_file_read / module_file_append |
 | module-manifest-tools | module_manifest |
 | module-import-tools | module_import |
+| soul-ledger | soul_ledger |
+| retrieval | module_search / module_open |
 | tool-config-engine | customTools 中的实际工具 |
 
 完整规则工具先读原始树与版本，再提交合法完整候选；删除整规则需显式 rule:null。变量工具提供 global/module 的 list/get/set/delete，set 必须显式字符串。模块私有文件（memory.md、assets/ 只读、data/ 只追加）由 module_file_read/append 读写，不自动注入；module_manifest 按 assets/manifest.yml 做 next/check/apply，只写 data/、不覆盖。
@@ -124,7 +128,19 @@ ST JSON 预设、PNG/JSON 角色卡和独立世界书，经统一预览/确认/
 
 outlet/vectorized/triggers 不能等价执行，相关规则禁用并报告；角色过滤、自动化、深度插入、预算、群聊和脚本都有明确限制。完整映射及报告边界见 [SillyTavern 导入](docs/SillyTavern.md)。
 
-模块导出分享完整定义和允许的附件，不分享全局变量或私有 memory.md。旧私有记忆标记必须显式处理，不靠删除标记继续导出。路径、链接、体积、覆盖和备份边界见 [资产交换](docs/asset-transfer.md)。
+模块导出分享完整定义和允许的附件，不分享全局变量、私有 memory.md 或 data/。旧私有记忆标记必须显式处理，不靠删除标记继续导出。路径、链接、体积、覆盖和备份边界见 [资产交换](docs/asset-transfer.md)。
+
+书房数据通过 `/prompt-tool data-import <JSON>` 显式导入。先指定 `moduleId`、来源书房根 `sourceDirectory` 和相对文件列表 `paths`，预览创建、跳过与冲突项；确认后在相同 JSON 中加上返回的 `expectedRevision`（值取预览的 `revision`）应用。只补缺失文件，冲突项保留目标，源文件不动；旧 `02-墨.jsonl` 映射到 `data/02-soul.jsonl`。新建书房用 `{"moduleId":"soul","initialize":true}` 预览模块自己的清单，也须带预览版本应用。完整例子与限制见 [数据导入](docs/architecture-params.md#书房数据预览与导入)。
+
+Soul 模块包含结构化账本、授权文件／历史检索、每步动态 SELF、上下文压缩与裁剪溯源、生成恢复和维护心跳。SELF 由 `rule-engine` 的内置动态内容源提供（`strategy: placeholder`、`fill: soul-self`），无需模块附带策略 JS。先用上述初始化预览补齐 `SELF.src.md` 骨架；已有模块副本须显式更新，包升级不会覆盖用户定义或私有数据，旧副本仍可使用自身保留的自定义策略。
+
+`soul_ledger` 自动署名真实会话，`lead` 需宿主审批，只有最后主导会话可追加 `promise`；通用文件追加拒绝新旧账本名。`module_search` 返回的引用交给 `module_open` 回取，历史会话只读取声明的白名单。SELF 的当前身份在每步读取时加入，维护默认每分钟只更新索引与快照，`wake` 独立且默认关闭。
+
+`generation-recovery` 的通用默认只截断；Soul 显式启用空回合检测和有界恢复，主会话额度 3、子代理 1，每会话独立且重挂不清零。维护压缩和扩大范围默认关闭。配置与边界见 [引擎运行时](docs/engine-reuse.md#重复输出安全截断)、[账本与SELF](docs/architecture-params.md#soul账本与派生快照)。
+
+这些运行能力由本插件实现，不需要源项目 `dsh-agent-soul` 的仓库、插件或后台服务；上下文治理仍要求宿主提供[官方能力包](docs/engine-reuse.md#上下文运行时与溯源)（按包名白名单从 DSH 自带包解析，运行期不比对版本）。本模块不等价于源项目的全部功能：检索采用授权范围内的字面匹配，未提供源近义检索、上下文水位提醒、完整 doctor/诊断工具或附属面板；恢复判据与额度策略也有差异。`assets/reference/` 保留的源文档用于背景参考，其中的源 CLI 和第三方工具不表示本插件已提供对应能力。
+
+上下文能力按包名白名单从 DSH 自带包解析，不增加插件依赖，运行期不校验版本；仅包缺失或未登记时拒绝该能力装配。包代码更新需要用户重启 DSH 加载；加载后修改模块启停／参数沿运行时刷新，不改官方 preset 或 profile patch。
 
 ## 升级与旧格式
 

package/engine/actions/catalog.mjs

@@ -74,7 +74,8 @@ export const ACTION_KINDS = Object.freeze({
     note: '一份声明拥有工具的可见面：allow/deny 名单、requireMatch、发现工具。名单语义对齐官方 '
       + 'ToolRestriction 的 and/or（同时给时先按 allow 保留、再按 deny 剔除）。deny 走 guard（本层与晚到工具）'
       + '与 restrict（继承的全局工具）；allow 只有 restrict 能覆盖全局工具，本层注册无法在执行层「只保留」——'
-      + '这是官方 restrict 的边界，不是本动作的取舍。',
+      + '这是官方 restrict 的边界，不是本动作的取舍。requireMatch 表达「名单与装配面整体错位」：'
+      + '名单里的名字一个都不存在才整面放宽，部分缺失只留诊断；解锁名不参与判定。',
   },
   'request-params': {
     title: '改模型请求参数',

package/engine/actions/index.mjs

@@ -83,9 +83,7 @@ export function prepareAction(action, options = {}) {
     const on = withWhen(options.on ?? channelBinder(ctx, kind, plugin, options.prepend === true), options.when, warnOnce, phase, missAll)
     // 每轮预算的轮边界由 durable 事件驱动（与谓词的 observe 同一事件源，但**独立记账**：
     // 预算是「本动作生效次数」，不是 durable 事件计数）。
-    if (budget !== undefined) collect(ctx.on('session/event', (session, event) => budget.observe(session, event)))
     const take = (subject) => budget?.take(subject) ?? true
-    bind?.(ctx, { warnOnce, on, collect, take, onMiss, agent: options.agent })
     const dispose = () => {
       for (const release of disposers.splice(0)) {
         try {
@@ -95,7 +93,11 @@ export function prepareAction(action, options = {}) {
         }
       }
     }
-    keepDisposer(ctx, dispose, `${plugin}: action ${labelOf(action)}`)
+    try {
+      if (budget !== undefined) collect(ctx.on('session/event', (session, event) => budget.observe(session, event)))
+      bind?.(ctx, { warnOnce, on, collect, take, onMiss, agent: options.agent })
+      keepDisposer(ctx, dispose, `${plugin}: action ${labelOf(action)}`)
+    } catch (error) { dispose(); throw error }
     // 调用方（rule-runtime）把 miss 挂到该动作的条目上；没有回调时保持 undefined。
     dispose.miss = missHandlers.length === 0 ? undefined : missAll
     return dispose

package/engine/actions/shared.mjs

@@ -37,20 +37,28 @@ export function createMask(source, label, plugin, allowExtra) {
     /** 动态白名单的落点（活集合，由调用方每轮重填）；未声明 allowFrom 时不存在。 */
     allowExtra,
     /**
-     * fail-open 兜底开关（**可选**，缺省 false）：原 `tool-bootstrap` 的语义是
-     * 「keep 名单里的工具在本次装配目录里一个都不存在 → 放弃裁剪、暴露完整目录」，而原
-     * `tool-filter` 的同名场景是**照名单裁成空目录**。两种语义都真实存在，所以这里
-     * **不设默认**——要兜底的声明自己写 `requireMatch: true`。把某一个模块的特有语义当成
-     * 通用默认，会让另一个声明路径的行为被悄悄改掉（这正是对拍抓出来的）。
+     * fail-open 兜底开关（**可选**，缺省 false）：判据是「这份名单与装配面整体错位」——
+     * 名单里的名字**一个都不存在**时放弃裁剪、暴露完整目录；部分缺失只留诊断，收窄照常
+     * 生效（提供方被替换或关闭是正常部署差异，见 {@link toolSurfacePlan}）。原
+     * `tool-bootstrap` 的同名语义就是「一个都不存在 → 放弃裁剪」，而原 `tool-filter` 是
+     * 「永远照名单裁」；两种语义都真实存在，所以这里**不设默认**——要兜底的声明自己写
+     * `requireMatch: true`。把某一个模块的特有语义当成通用默认，会让另一个声明路径的行为
+     * 被悄悄改掉（这正是对拍抓出来的）。
      */
     requireMatch: source?.requireMatch === true,
-    /** 与 tool-filter 的名单判据 / Layer.admits 同一判据（tool-filter 模块已删除，判据保留）。 */
-    blocks: (toolName) => {
+    /**
+     * 与 tool-filter 的名单判据 / Layer.admits 同一判据（tool-filter 模块已删除，判据保留）。
+     *
+     * 第二个参数是**解锁项快照**：allowExtra 是跨 agent 共享的活集合，每次装配都会 clear 后
+     * 按当前会话重填；执行闸在该装配之后才被调用，必须读自己会话的冻结快照，否则别的会话
+     * （或探针装配）会把本会话的解锁名抹掉。缺省仍是活集合，供同一次装配内的裁剪使用。
+     */
+    blocks: (toolName, extra = allowExtra) => {
       if (typeof toolName !== 'string' || toolName.length === 0) return false
       // 保留传输不参与任何名单：allow 没点名也必须留下，deny 已在挂载期拒绝。
       if (toolName === RUN_CODE) return false
       if (deny !== undefined && deny.has(toolName)) return true
-      if (allowExtra?.has(toolName) === true) return false
+      if (extra?.has(toolName) === true) return false
       // 声明了 allow、或声明了 allowFrom（= 白名单模式，静态名单视为空集），未点名即裁掉。
       return (allow !== undefined || allowExtra !== undefined) && allow?.has(toolName) !== true
     },
@@ -60,17 +68,23 @@ export function createMask(source, label, plugin, allowExtra) {
 /**
  * 工具可见面的单一判据：装配目录、`tools:sdk` 正文与执行闸共用同一份 fail-open 决定。
  *
- * `available` = 目录名 ∪ SDK 正文名；`required` = 静态 allow ∪ 动态解锁项，再剔掉
+ * `available` = 目录名 ∪ SDK 正文名；`required` 只取**静态 allow**，再剔掉
  * `run_code`（保留传输）与 `mask.blocks()` 为真的名字（deny 覆盖者不该被要求存在）。
- * 缺项时三面必须一起放宽——只放宽一面会让模型看到的与能调的不一致。
+ *
+ * 放宽条件是「名单里的名字**一个都不存在**」：那才说明装配面与声明整体错位（换了一套
+ * 部署/平台）。只缺一部分是提供方被替换或关掉的正常部署差异——照常收窄，缺的工具由发现
+ * 通道补位，替换提供方的名字由部署层名单登记。解锁名（allowExtra）**不参与判定**：它是只做
+ * 加法的提示，若参与，模型解锁一个拼错或已改名的工具就能关掉收窄。
+ *
+ * 放宽时三面必须一起放宽——只放宽一面会让模型看到的与能调的不一致。
  */
 export function toolSurfacePlan(mask, available) {
   // 动作层的挂载期校验（prepareToolVisibility）已拒绝 requireMatch + 无 allow。
   const required = mask.requireMatch
-    ? [...new Set([...(mask.allow ?? []), ...(mask.allowExtra ?? [])])].filter((name) => name !== RUN_CODE && !mask.blocks(name))
+    ? [...new Set(mask.allow ?? [])].filter((name) => name !== RUN_CODE && !mask.blocks(name))
     : []
   const missing = required.filter((name) => !available.has(name))
-  return { failOpen: missing.length > 0, missing }
+  return { failOpen: required.length > 0 && missing.length === required.length, missing }
 }
 
 export function requireString(value, label, plugin) {

package/engine/actions/tool-visibility.mjs

@@ -13,8 +13,10 @@
  *
  * 名单语义对齐官方 ToolRestriction（deepseek-harness packages/core/tools/src/index.ts:701-706）：
  * allow 与 deny 可以同时给，判据是「先按 allow 保留，再按 deny 剔除」。requireMatch 只在
- * allow 模式有意义：名单里任一工具在目录与 SDK 正文的并集里都找不到，就放弃裁剪、暴露完整目录（fail-open）并告警——
- * 收窄错了会让当前工作流调不到工具，比多花上下文严重。
+ * allow 模式有意义，判据是「这份名单与装配面整体错位」：名单里的名字**一个都不在**目录与
+ * SDK 正文的并集里，才放弃裁剪、暴露完整目录（fail-open）并告警。只缺一部分是提供方被
+ * 替换或关闭的正常部署差异，收窄照常生效、缺项只留一条诊断；解锁名是只做加法的提示，
+ * 不参与这个判定。
  *
  * 执行边界：deny 同时用 restrict（继承面）与 guard（本层/晚到）；allow 不用 restrict——
  * 它的 allow 只能收继承面名字，而 `schemas()` 全局视图会漏掉预设/祖先层，局部 allow 会
@@ -110,7 +112,8 @@ export function prepareToolVisibility(action, plugin) {
     const capability = createAgentCapability((agent) => {
       const tools = agent?.ctx?.tools
       if (tools === undefined) return undefined
-      const state = { failOpen: false }
+      // unlocked：本会话装配时冻结的解锁名快照（await next() 期间别的装配会重填共享集合）。
+      const state = { failOpen: false, unlocked: undefined }
       const disposers = []
       try {
         const known = toolScopeSnapshot(tools).globalNames
@@ -135,8 +138,11 @@ export function prepareToolVisibility(action, plugin) {
             const toolName = exec?.name
             if (toolName === RUN_CODE || typeof toolName !== 'string' || toolName.length === 0) return undefined
             if (deny?.has(toolName)) return `${label}: tool ${JSON.stringify(toolName)} is denied by tool-visibility`
-            if (mask.allow !== undefined && !state.failOpen && mask.blocks(toolName)) {
-              return `${label}: tool ${JSON.stringify(toolName)} is not allowed by tool-visibility`
+            if (mask.allow !== undefined && !state.failOpen && mask.blocks(toolName, state.unlocked)) {
+              const hint = discovery === undefined
+                ? 'the allow list is the only path; this action has no discovery source'
+                : `unlock it with tool_search({"toolNames":[${JSON.stringify(toolName)}]}); the gate allows unlocked tools from the next request on`
+              return `${label}: tool ${JSON.stringify(toolName)} is not allowed by tool-visibility; ${hint}`
             }
             return undefined
           }))
@@ -148,8 +154,9 @@ export function prepareToolVisibility(action, plugin) {
       return { disposers, data: state }
     })
 
-    const syncGate = (agent) => {
-      const key = `${maskKey(mask)}|unlock:${allowExtra === undefined ? '' : [...allowExtra].sort().join(',')}`
+    // 重挂判定用**本会话的快照**：共享集合在别的装配里会被重填，不能当身份。
+    const syncGate = (agent, unlocked) => {
+      const key = `${maskKey(mask)}|unlock:${unlocked === undefined ? '' : [...unlocked].sort().join(',')}`
       capability.sync(agent, key)
     }
 
@@ -183,8 +190,11 @@ export function prepareToolVisibility(action, plugin) {
           fillUnlocked(allowExtra, context?.session ?? context?.agent?.session, unlock.tool, unlock.key, warnOnce, plugin, label)
         }
       }
+      // 在 await next() 之前冻结本会话的解锁名：之后的裁剪与执行闸都读这一份，
+      // 共享的 allowExtra 可能被并发的另一次装配（别的会话 / 探针）清空重填。
+      const unlocked = allowExtra === undefined ? undefined : new Set(allowExtra)
       try {
-        syncGate(context?.agent)
+        syncGate(context?.agent, unlocked)
       } catch (error) {
         // 闸注册失败必须留痕；呈现面照常结算，绝不把异常抛给装配。
         warnOnce(`${plugin}: tool-visibility action ${label} failed to sync execution gate: ${String(error?.message ?? error)}`)
@@ -204,16 +214,23 @@ export function prepareToolVisibility(action, plugin) {
         // 没有工具面可观（既无目录也无 SDK 正文）时不裁剪、不告警、不动执行闸：
         // 空 surface 不等于「名单全缺」；空目录（tools=[]）仍是真实观测，照旧 fail-open。
         if (!Array.isArray(result.tools) && sdkSection === undefined) return result
-        // 三面（目录 / 正文 / 执行闸）共用这一份判断：缺项就整体放宽，呈现与执行不得两套口径。
+        // 三面（目录 / 正文 / 执行闸）共用这一份判断：名单全缺才整体放宽，呈现与执行不得两套口径。
         const plan = toolSurfacePlan(mask, available)
         const state = capability.get(context?.session ?? context?.agent?.session)
-        if (state !== undefined) state.data.failOpen = plan.failOpen
+        if (state !== undefined) {
+          state.data.failOpen = plan.failOpen
+          state.data.unlocked = unlocked
+        }
         if (plan.failOpen) {
-          // 去重键固定到动作：缺项名随解锁历史变化，不能让每个新集合各占一条 warnOnce。
-          warnOnce(`${plugin}: tool-visibility action ${label}: requireMatch tools absent (${plan.missing.join(', ')}) — exposing the full tool set (fail-open)`, `${plugin}: tool-visibility action ${label}: requireMatch fail-open`)
+          // 去重键固定到动作：缺项名随部署变化，不能让每个新集合各占一条 warnOnce。
+          warnOnce(`${plugin}: tool-visibility action ${label}: none of the resident tools exist (${plan.missing.join(', ')}) — exposing the full tool set (fail-open)`, `${plugin}: tool-visibility action ${label}: requireMatch fail-open`)
         } else {
+          // 部分缺失不改变裁剪，但必须留痕：否则「某个常驻工具为什么不见了」只能靠猜。
+          if (plan.missing.length > 0) {
+            warnOnce(`${plugin}: tool-visibility action ${label}: resident tools absent (${plan.missing.join(', ')}) — narrowing continues; register replacement providers in the deployment allow list`, `${plugin}: tool-visibility action ${label}: resident tools absent`)
+          }
           if (Array.isArray(result.tools)) {
-            const kept = result.tools.filter((tool) => !mask.blocks(tool?.name))
+            const kept = result.tools.filter((tool) => !mask.blocks(tool?.name, unlocked))
             if (kept.length !== result.tools.length) result = { ...result, tools: kept }
           }
           if (Array.isArray(result.sections)) {
@@ -227,7 +244,7 @@ export function prepareToolVisibility(action, plugin) {
               }
               const names = mask.allow === undefined
                 ? mask.deny
-                : new Set([...presentNames()].filter((name) => mask.blocks(name)))
+                : new Set([...presentNames()].filter((name) => mask.blocks(name, unlocked)))
               if (names === undefined || names.size === 0) return section
               const stripped = stripSdkDeclarations(section.text, names)
               if (stripped === section.text) return section

package/engine/compositions/source/local/context-provenance.yml

@@ -0,0 +1,9 @@
+- id: context-provenance
+  name: ./engine/context-provenance.mjs
+  config:
+    enabled: true
+    audience: all
+    auto: true
+    modelSwitch: true
+    prune: true
+    recoveryRetainTokens: 1024

package/engine/compositions/source/local/generation-recovery.yml

@@ -0,0 +1,10 @@
+# module: generation-recovery
+# 精确重复安全截断；不自动续跑，不处理压缩或标题等辅助模型调用。
+- id: generation-recovery
+  name: ./engine/generation-recovery.mjs
+  config:
+    enabled: true
+    audience: all
+    textRepeatChars: 4096
+    reasoningRepeatChars: 8192
+    maxCycleChars: 256

package/engine/compositions/source/local/retrieval.yml

@@ -0,0 +1,7 @@
+# module: retrieval
+- id: retrieval
+  name: ./engine/retrieval.mjs
+  config:
+    enabled: true
+    paths: []
+    sessions: []

package/engine/compositions/source/local/soul-ledger.yml

@@ -0,0 +1,3 @@
+# module: soul-ledger
+- id: soul-ledger
+  name: ./engine/soul-ledger.mjs

package/engine/compositions/source/local/soul-maintenance.yml

@@ -0,0 +1,9 @@
+# module: soul-maintenance
+- id: soul-maintenance
+  name: ./engine/soul-maintenance.mjs
+  config:
+    enabled: true
+    intervalMs: 60000
+    wake: false
+    audience: all
+    budgetBytes: 12288

package/engine/conditions/examples.mjs

@@ -9,4 +9,5 @@ export const PREDICATE_EXAMPLES = {
   scope: { audience: 'main', modelScope: 'all' },
   anchor: { subject: 'assistantReasoning', keys: ['确认'], mode: 'prefix' },
   variable: { key: 'quota', op: 'lte', value: '0', scope: 'effective' },
+  manifest: { ok: true },
 }

package/engine/conditions/index.mjs

@@ -8,6 +8,7 @@ import { createPresetPredicate } from './preset.mjs'
 import { createScopePredicate } from './scope.mjs'
 import { createAnchorPredicate } from './anchor.mjs'
 import { createVariablePredicate } from './variable.mjs'
+import { createManifestPredicate } from './manifest.mjs'
 import { withAvailableInput } from './availability.mjs'
 import { composite } from './composite.mjs'
 import { COMPOSITE_OPERATORS } from './operators.mjs'
@@ -21,6 +22,7 @@ export * from './preset.mjs'
 export * from './scope.mjs'
 export * from './anchor.mjs'
 export * from './variable.mjs'
+export * from './manifest.mjs'
 export { subjectOf, channelTextSubjects, channelFactSubjects, FACT_PREDICATE_SUBJECTS } from './subject.mjs'
 export { composite } from './composite.mjs'
 export const PREDICATE_FACTORIES = Object.freeze({
@@ -34,6 +36,7 @@ export const PREDICATE_FACTORIES = Object.freeze({
   scope: createScopePredicate,
   anchor: createAnchorPredicate,
   variable: createVariablePredicate,
+  manifest: createManifestPredicate,
 })
 export { COMPOSITE_OPERATORS }
 
@@ -95,5 +98,9 @@ export function compileWhen(node, context = {}) {
   if (key === 'variable') {
     return createVariablePredicate(options, { store: context.variableStore, moduleId: context.moduleId })
   }
+  // manifest 谓词同样自带三值：读取器未绑定或清单不可读时为 UNAVAILABLE。
+  if (key === 'manifest') {
+    return createManifestPredicate(options, { manifestCheck: context.manifestCheck, moduleId: context.moduleId })
+  }
   return withAvailableInput(key, options, factory(options))
 }

package/engine/conditions/manifest.mjs

@@ -0,0 +1,28 @@
+/**
+ * manifest 谓词：规则读取来源模块 `assets/manifest.yml` 的 checks 事实。
+ *
+ * 读取器由宿主装配经 options 在挂载期绑定，结果缓存 1000ms，清单戳变化提前失效；
+ * 读取器缺失、清单缺失/损坏都判 UNAVAILABLE——不能经 not 反转，也不能当「检查失败」。
+ */
+import { UNAVAILABLE } from './availability.mjs'
+
+/**
+ * @param {{ ok?: boolean }} options
+ * @param {{ manifestCheck?: { read: (moduleId: string) => boolean | undefined }, moduleId?: string }} [context]
+ */
+export function createManifestPredicate(options = {}, context = {}) {
+  const unknown = Object.keys(options).filter((key) => key !== 'ok')
+  if (unknown.length > 0) throw new TypeError(`predicates: manifest does not take ${unknown.join(', ')}`)
+  if (typeof options.ok !== 'boolean') throw new TypeError('predicates: manifest ok must be a boolean')
+  const expected = options.ok
+  const reader = context.manifestCheck
+  const moduleId = context.moduleId
+  const predicate = () => {
+    if (reader === undefined || typeof reader.read !== 'function') return UNAVAILABLE
+    if (typeof moduleId !== 'string' || moduleId.length === 0) return UNAVAILABLE
+    const observed = reader.read(moduleId)
+    return typeof observed === 'boolean' ? observed === expected : UNAVAILABLE
+  }
+  predicate.kind = 'manifest'
+  return predicate
+}

package/engine/context-idle-compaction.mjs

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto'
+import { isDeepStrictEqual } from 'node:util'
+import { importHostCapability } from './host-package.mjs'
+import { frameSummary } from './context-summary.mjs'
+import { historyEvents } from './history.mjs'
+
+/** 已领取idle维护窗口内的局部事务；Basic.compactRegion仅允许打开的turn。 */
+export async function compactIdleRegion({ agent, range, signal, meter, sessions, compaction, pairing }) {
+  signal.throwIfAborted()
+  const { createUserMessage, errorChain } = await importHostCapability('@deepseek-ai/dsh-llm')
+  signal.throwIfAborted()
+  const session = agent.session, nodes = session.surface.nodes
+  const start = nodes.indexOf(range.start), end = nodes.indexOf(range.end)
+  if (start < 0 || end < start || !pairing.toolPairingBalancedBefore(session, range.start)
+    || !pairing.toolPairingBalancedAfter(session, range.end)) throw new Error('idle compaction: invalid balanced range')
+  const history = historyEvents(session), bySeq = new Map(history.map(event => [event.seq, event]))
+  const turn = history.findLast(event => event.type === 'turn/start' || event.type === 'turn/end')
+  if (turn?.type === 'turn/start') throw new Error('idle compaction: turn is open')
+  const lock = history.findLast(event => ['compaction/start', 'compaction/end', 'session/end-seed'].includes(event.type))
+  if (lock?.type === 'compaction/start') throw new Error('idle compaction: already running')
+  const seqs = nodes.slice(start, end + 1)
+  const selected = meter.measure(session).nodes.slice(start, end + 1)
+  if (!isDeepStrictEqual(selected.map(n => n.seq), seqs)) throw new Error('idle compaction: stale pricing')
+  const original = seqs.map(seq => bySeq.get(seq))
+  if (original.some(event => !event)) throw new Error('idle compaction: source event missing')
+  if (original.some(event => event.type === 'system/message')) throw new Error('idle compaction: system head cannot be replaced')
+  const messages = original.map(event => session.deriveEventMessage(event)).filter(Boolean)
+  const head = bySeq.get(nodes[0])
+  if (head?.type === 'system/message') messages.unshift(session.deriveEventMessage(head))
+  const header = session.requestHeader()
+  const lifecycle = { compactionId: randomUUID(), turn: null }
+  const startEvent = session.append('compaction/start', lifecycle)
+  let closing = false
+  try {
+    const summary = await compaction.summarize({ messages, ...(header?.tools ? { tools: header.tools } : {}) }, agent, signal)
+    signal.throwIfAborted()
+    const current = session.surface.nodes, first = current.indexOf(range.start)
+    const currentEvents = new Map(historyEvents(session).map(event => [event.seq, event]))
+    if (!isDeepStrictEqual(current.slice(first, first + seqs.length), seqs)
+      || !isDeepStrictEqual(seqs.map(seq => currentEvents.get(seq)), original)
+      || !isDeepStrictEqual(meter.measure(session).nodes.slice(first, first + seqs.length), selected)) throw new Error('idle compaction: selected surface changed')
+    const checkpoint = createUserMessage({ content: frameSummary(summary.summary), source: pairing.compactCheckpointSource(lifecycle.compactionId) })
+    if (meter.estimateMessage(checkpoint) >= selected.reduce((sum, node) => sum + node.tokens, 0)) throw new Error('idle compaction: summary is not smaller')
+    const shadowedTokenCount = selected.reduce((sum, node) => sum + node.heuristicTokens, 0)
+    const summaryEvent = session.append('compaction/summary', { ...summary, compactionId: lifecycle.compactionId,
+      shadowedRange: range, shadowedSeqs: seqs, shadowedTokenCount })
+    signal.throwIfAborted()
+    session.append('user/message', checkpoint, { surfaceOp: { op: 'replace', startSeq: range.start, endSeq: range.end }, sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...seqs] })
+    signal.throwIfAborted()
+    closing = true
+    const endEvent = session.append('compaction/end', lifecycle)
+    return { compactionId: lifecycle.compactionId, startSeq: startEvent.seq, summarySeq: summaryEvent.seq, endSeq: endEvent.seq,
+      summary: summary.summary, shadowedRange: range, shadowedSeqs: seqs, shadowedTokenCount }
+  } catch (error) {
+    if (!closing) { closing = true; session.append('compaction/end', { ...lifecycle, error: errorChain(error) }) }
+    throw error
+  } finally { await sessions.flush(session) }
+}

package/engine/context-provenance.d.mts

@@ -0,0 +1,7 @@
+export interface ContextRuntime {
+  compactNow(signal?: AbortSignal): Promise<unknown>
+  compactRegion(start: number, end: number, signal?: AbortSignal): Promise<unknown>
+  compactRecovery(signal?: AbortSignal): Promise<unknown>
+  status(): { state: string; last: unknown }
+}
+export function contextRuntimeOf(agent: object): ContextRuntime | undefined

package/engine/context-provenance.mjs

@@ -0,0 +1,156 @@
+import { Context } from '@deepseek-ai/cordis'
+import { bool, defineConfig, enumOf, int, passthrough } from './fields.mjs'
+import { capabilityAudience } from './agent-capability.mjs'
+import { importHostCapability } from './host-package.mjs'
+import { routeContextRuntime } from './context-routing.mjs'
+import { createProvenancePruner } from './context-pruner.mjs'
+import { createProvenanceCompaction } from './context-summary.mjs'
+import { compactIdleRegion } from './context-idle-compaction.mjs'
+import { historyEvents } from './history.mjs'
+
+export const name = 'context-provenance'
+export const inject = ['llm', 'sessions', 'tokenMeter']
+const configObject = passthrough((value, plugin, field) => {
+  if (value === undefined) return {}
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${plugin}: ${field} must be an object`)
+  return value
+})
+export const configContract = defineConfig({
+  enabled: bool({ default: false }), audience: enumOf(['all', 'main', 'subagent'], { default: 'all' }),
+  auto: bool({ default: true }), modelSwitch: bool({ default: true }), prune: bool({ default: true }),
+  basic: configObject, pruner: configObject,
+  recoveryRetainTokens: int({ min: 0, default: 1024 }),
+})
+const runtimes = new WeakMap()
+export const contextRuntimeOf = agent => runtimes.get(agent)
+
+/** 用真实surface位置与配对边界选区；保留尾部，不把seq当连续整数。 */
+export function compactableRange(session, measurement, retainTokens, pairing) {
+  const nodes = measurement.nodes
+  const events = new Map(historyEvents(session).map(event => [event.seq, event]))
+  if (nodes.some(node => !events.has(node.seq))) throw new Error('context-provenance: surface event missing')
+  let first = nodes.findIndex(node => events.get(node.seq).type !== 'system/message')
+  if (first < 0) return null
+  while (first < nodes.length && !pairing.toolPairingBalancedBefore(session, nodes[first].seq)) first++
+  let retained = 0, last = nodes.length - 1
+  while (last >= first && retained < retainTokens) retained += nodes[last--].tokens
+  while (last >= first && !pairing.toolPairingBalancedAfter(session, nodes[last].seq)) last--
+  return last < first ? null : { start: nodes[first].seq, end: nodes[last].seq }
+}
+
+/** 宿主依赖是实际适配器接缝，隔离验证可提供同版本官方构造器。 */
+export async function mountContextRuntime(ctx, raw, { agent, sourceModuleId }, packages) {
+  const config = configContract.parse(raw, name)
+  if (!config.enabled || !agent || config.audience !== 'all' && config.audience !== capabilityAudience(agent)) return
+  if (runtimes.has(agent)) throw new Error('context-provenance: Agent already has a runtime owner')
+  ctx.fiber.assertActive()
+  const { Basic, Pruner, pairing } = packages
+  const privateCtx = new Context()
+  const lifetime = new AbortController()
+  let active = true
+  const status = { state: 'ready', last: null }
+  const off = []
+  let offRoute = () => {}, runtime
+  // 先登记所有权再等待构造器，父scope在await期间释放也能取消私有实例。
+  const dispose = ctx.effect(() => () => {
+    active = false; lifetime.abort(); status.state = 'disabled'
+    if (runtime && runtimes.get(agent) === runtime) runtimes.delete(agent)
+    offRoute(); for (const remove of off) remove()
+    return privateCtx.fiber.dispose()
+  })
+  const meter = ctx.get('tokenMeter'), llm = ctx.get('llm'), sessions = ctx.get('sessions')
+  // 只把公开方法绑定到原服务；私有Context不接管共享服务生命周期。
+  privateCtx.provide('tokenMeter', { measure: (...args) => meter.measure(...args), estimateMessage: message => meter.estimateMessage(message) })
+  privateCtx.provide('llm', { stream: options => llm.stream(options), resolveModelInfo: (...args) => llm.resolveModelInfo(...args) })
+  privateCtx.provide('sessions', { flush: session => sessions.flush(session) })
+  const combined = signal => signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal
+  const check = signal => { combined(signal).throwIfAborted() }
+  const Compaction = createProvenanceCompaction(Basic, { sourceModuleId, isActive: () => active, signalOf: () => lifetime.signal })
+  try {
+    if (config.prune) {
+      const CitedPruner = createProvenancePruner(Pruner, { sourceModuleId, isActive: () => active, signalOf: () => lifetime.signal })
+      await privateCtx.plugin(CitedPruner, config.pruner)
+      check()
+    }
+    await privateCtx.plugin(Compaction, { ...config.basic, auto: config.auto })
+    check()
+  } catch (error) { await dispose(); throw error }
+  const compaction = privateCtx.get('compaction'), pruner = privateCtx.get('toolResultPruner')
+  const run = async (action, signal) => {
+    check(signal); status.state = 'running'
+    try {
+      const result = await action(combined(signal))
+      check(signal)
+      status.state = result === null ? 'no-op' : 'success'; status.last = result
+      return result
+    } catch (error) { status.state = combined(signal).aborted ? 'cancelled' : 'failed'; throw error }
+  }
+  runtime = {
+    status: () => ({ ...status }),
+    compactNow: (signal, commandId) => run(abort => compaction.compactNow(agent, abort, commandId), signal),
+    compactRegion: (start, end, signal) => run(abort => agent.status === 'idle'
+      ? agent.runMaintenance(maintenanceSignal => compactIdleRegion({ agent, range: { start, end },
+        signal: AbortSignal.any([abort, maintenanceSignal]), meter, sessions, compaction, pairing }))
+      : compaction.compactRegion(start, end, agent, abort), signal),
+    compactRecovery: signal => run(abort => agent.runMaintenance(async maintenanceSignal => {
+      const operation = AbortSignal.any([abort, maintenanceSignal])
+      operation.throwIfAborted()
+      const range = compactableRange(agent.session, meter.measure(agent.session), config.recoveryRetainTokens, pairing)
+      if (!range) return null
+      return compactIdleRegion({ agent, range, signal: operation, meter, sessions, compaction, pairing })
+    }), signal),
+  }
+  try {
+  runtimes.set(agent, runtime)
+  offRoute = routeContextRuntime(ctx, agent, {
+    compaction: {
+      compactNow: (_owner, signal, commandId) => runtime.compactNow(signal, commandId),
+      compactRegion: (start, end, _owner, signal) => runtime.compactRegion(start, end, signal),
+      compactIfNeeded: (_owner, trigger, signal) => run(abort => compaction.compactIfNeeded(agent, trigger, abort), signal),
+    },
+    toolResultPruner: pruner ? { pruneSession: session => { check(); return pruner.pruneSession(session, lifetime.signal) } } : undefined,
+  })
+  for (const event of ['agent/pre-step', 'agent/request-error']) off.push(ctx.on(event, async (payload, next) => {
+    if (!active || payload.agent !== agent) return next()
+    const result = await privateCtx.waterfall(event, { ...payload, signal: combined(payload.signal) }, () => undefined)
+    return result === undefined ? next() : result
+  }, { prepend: true }))
+  // Basic的retry账本按官方durable结算与idle复位。
+  off.push(ctx.on('session/event', (session, event) => { if (active && session === agent.session) privateCtx.emit('session/event', session, event) }))
+  off.push(ctx.on('agent/status', payload => { if (active && payload.agent === agent) privateCtx.emit('agent/status', payload) }))
+  if (config.modelSwitch) off.push(ctx.on('agent/request', async (payload, next) => {
+    const request = await next()
+    if (!active || payload.agent !== agent || payload.signal?.aborted) return request
+    const previous = agent.session.requestHeader()
+    if (!previous || previous.config.provider === request.provider && previous.config.model === request.model) return request
+    const signal = combined(payload.signal)
+    const info = await llm.resolveModelInfo(request.provider, request.model, signal)
+    check(signal)
+    const policy = { ...compaction.config, ...(compaction.config.modelPolicies?.find(p => p.provider === request.provider && p.model === request.model) ?? {}) }
+    const capacity = info.context?.contextWindow
+    const reserved = request.maxTokens ?? info.defaultMaxTokens ?? 0
+    if (!Number.isFinite(capacity) || capacity <= reserved + policy.headroomTokens) throw new Error('context-provenance: model switch has no message budget')
+    const threshold = Math.floor(Math.min(capacity * policy.thresholdRatio, capacity - reserved - policy.headroomTokens))
+    const retain = policy.retainTokens ?? Math.floor((capacity - reserved) * policy.retainRatio)
+    if (retain >= threshold) throw new Error('context-provenance: model switch retention exceeds budget')
+    for (let attempt = 0; ; attempt++) {
+      const measurement = meter.measure(agent.session, { ...previous, config: { ...previous.config, ...request } })
+      if (measurement.totalTokens < threshold) return request
+      if (attempt > policy.compactionRetries) throw new Error('context-provenance: model switch remains above budget')
+      const range = compactableRange(agent.session, measurement, retain, pairing)
+      if (!range) throw new Error('context-provenance: model switch has no compactable range')
+      await runtime.compactRegion(range.start, range.end, signal)
+    }
+  }, { prepend: true }))
+  return dispose
+  } catch (error) { await dispose(); throw error }
+}
+
+export async function apply(ctx, config, options = {}) {
+  const parsed = configContract.parse(config, name)
+  if (!parsed.enabled) return
+  const [{ BasicCompactionEngine: Basic }, { ToolResultPruner: Pruner }, pairing] = await Promise.all([
+    importHostCapability('@deepseek-ai/dsh-compaction-basic'), importHostCapability('@deepseek-ai/dsh-compaction-tool-result-pruner'), importHostCapability('@deepseek-ai/dsh-compaction'),
+  ])
+  return mountContextRuntime(ctx, parsed, options, { Basic, Pruner, pairing })
+}