dsh-plugin-prompt-tool 3.0.2 → 3.1.1

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/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/tool-visibility.mjs

@@ -139,7 +139,10 @@ export function prepareToolVisibility(action, plugin) {
             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, state.unlocked)) {
-              return `${label}: tool ${JSON.stringify(toolName)} is not allowed by tool-visibility`
+              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
           }))

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

package/engine/context-pruner.mjs

@@ -0,0 +1,64 @@
+import { makeSessionReference } from './retrieval-reference.mjs'
+
+const PRUNE_MARKER = '\n\n[... tool result middle pruned ...]\n\n'
+
+/** 官方裁剪算法不变，只在本次生成marker的Unicode位置附来源。 */
+function referencedContent(content, headChars, reference) {
+  const result = [...content]
+  let consumed = 0
+  for (let index = 0; index < result.length; index++) {
+    const block = result[index]
+    if (block.type !== 'text') continue
+    const points = [...block.text]
+    if (consumed + points.length <= headChars) { consumed += points.length; continue }
+    const offset = headChars - consumed
+    if (points.slice(offset, offset + [...PRUNE_MARKER].length).join('') !== PRUNE_MARKER) return null
+    result[index] = { ...block, text: points.slice(0, offset).join('') + PRUNE_MARKER + `[source: ${JSON.stringify(reference)}]\n` + points.slice(offset + [...PRUNE_MARKER].length).join('') }
+    return result
+  }
+  return null
+}
+
+export function createProvenancePruner(PrunerClass, { sourceModuleId, isActive = () => true, signalOf = () => undefined, makeReference = makeSessionReference } = {}) {
+  return class ProvenancePruner extends PrunerClass {
+    pruneSession(session, signal = signalOf()) {
+      const check = () => {
+        signal?.throwIfAborted()
+        if (!isActive()) throw new Error('context-provenance: pruner released')
+      }
+      check()
+      const events = session.snapshotEvents()
+      const bySeq = new Map(events.map(event => [event.seq, event]))
+      const candidates = [...new Set(session.surface.nodes)].map(seq => bySeq.get(seq)).filter(event => event?.type === 'tool/result')
+      const pruned = []
+      let charsRemoved = 0
+      for (const event of candidates) {
+        check()
+        const seq = event.seq, original = session.deriveEventMessage(event)
+        let content = super.pruneContent(original.content)
+        if (content === null) continue
+        const charsBefore = this.measureContent(original.content)
+        try {
+          const reference = makeReference(sourceModuleId, session.id, events, [seq])
+          const cited = referencedContent(content, this.config.headChars, reference)
+          if (!cited || this.measureContent(cited) > this.config.thresholdChars || this.measureContent(cited) >= charsBefore) throw new Error('reference exceeds pruning budget')
+          content = cited
+        } catch (error) {
+          this.ctx.logger?.warn?.(`context-provenance: pruned without reference (${String(error?.message ?? error)})`)
+        }
+        const charsAfter = this.measureContent(content)
+        if (charsAfter > this.config.thresholdChars || charsAfter >= charsBefore) throw new Error('context-provenance: invalid prune result')
+        const shadowedTokenCount = this.ctx.tokenMeter.estimateMessage(original)
+        check()
+        session.append('compaction/prune', { shadowedRange: { start: seq, end: seq }, shadowedSeqs: [seq], shadowedTokenCount })
+        check()
+        const replacement = session.append('tool/result', { ...event.data, message: { ...original, content } }, {
+          surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq }, sourceEventSeqs: [seq],
+        })
+        pruned.push({ originalSeq: seq, replacementSeq: replacement.seq, callId: original.source.callId, charsBefore, charsAfter })
+        charsRemoved += charsBefore - charsAfter
+      }
+      return { pruned, charsRemoved }
+    }
+  }
+}

package/engine/context-routing.mjs

@@ -0,0 +1,45 @@
+import { Context } from '@deepseek-ai/cordis'
+
+/** 只路由声明Agent，原provider的方法和其它监听器保持原所有权。 */
+export function routeContextRuntime(ctx, agent, runtime) {
+  let active = true
+  const disposers = []
+  for (const service of ['compaction', 'toolResultPruner']) {
+    if (!runtime[service]) continue
+    const dependency = ctx.inject([service], dependent => {
+      // 已发布Fiber.store公开了这次依赖快照的精确provider身份。
+      const owner = dependent.fiber.store[service].fiber
+      const carriers = new WeakMap()
+      const offDispatch = service === 'compaction' ? dependent.on('internal/dispatch', (_mode, event, args, carrier) => {
+        if (!active || !['agent/pre-step', 'agent/request-error', 'agent/request'].includes(event)
+          || args[0]?.agent !== agent || !carrier) return
+        if (carriers.has(carrier)) return
+        const original = carrier[Context.filter]
+        const filter = function (candidate) {
+          return (!original || original.call(this, candidate)) && (!active || candidate.fiber !== owner)
+        }
+        carriers.set(carrier, original)
+        carrier[Context.filter] = filter
+      }) : () => {}
+      const offGet = dependent.on('internal/get', (_consumer, key, _error, next) => {
+        const original = next()
+        if (!active || key !== service || !original) return original
+        return new Proxy(original, {
+          get(target, property) {
+            const method = target[property]
+            if (typeof method !== 'function') return method
+            return (...args) => {
+              const subject = service === 'toolResultPruner' ? args[0] : property === 'compactRegion' ? args[2] : args[0]
+              const selected = service === 'toolResultPruner' ? subject === agent.session : subject === agent
+              if (active && selected && typeof runtime[service][property] === 'function') return runtime[service][property](...args)
+              return method.apply(target, args)
+            }
+          },
+        })
+      }, { prepend: true })
+      return () => { offDispatch(); offGet() }
+    })
+    disposers.push(() => dependency.dispose())
+  }
+  return () => { active = false; for (const dispose of disposers) void dispose() }
+}

package/engine/context-summary.mjs

@@ -0,0 +1,80 @@
+import { makeSessionReference } from './retrieval-reference.mjs'
+
+// shortcut: Basic alpha.2 未公开导出frameSummary，升级官方framing时同步此版本化快照。
+const CHECKPOINT_OPEN = 'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>'
+export function frameSummary(summary) {
+  return [{ type: 'text', text: CHECKPOINT_OPEN }, ...summary, { type: 'text', text: '</compacted-summary>' }]
+}
+const framed = summary => ({
+  id: 'context-provenance-budget', role: 'user', source: { kind: 'compact-checkpoint', compactionId: 'context-provenance-budget' },
+  content: frameSummary(summary),
+})
+
+function sourceSnapshot(input, session, meter) {
+  const events = session.snapshotEvents(), bySeq = new Map(events.map(event => [event.seq, event]))
+  const nodes = session.surface.nodes.map(seq => {
+    const event = bySeq.get(seq)
+    if (!event) throw new Error('source event missing')
+    return { seq, message: session.deriveEventMessage(event) }
+  })
+  let messages = input.messages
+  const head = nodes[0]?.message
+  // Basic 把system头作为缓存前缀再加一次；真正选中system时后面仍保留它。
+  if (head?.role === 'system' && messages[0]?.id === head.id) messages = messages.slice(1)
+  if (!messages.length || messages.some(message => typeof message.id !== 'string' || !message.id)) throw new Error('source message identity unavailable')
+  const matches = []
+  for (let start = 0; start < nodes.length; start++) {
+    if (nodes[start].message?.id !== messages[0].id) continue
+    let position = 0
+    for (let end = start; end < nodes.length; end++) {
+      const message = nodes[end].message
+      if (message !== null) {
+        if (message?.id !== messages[position]?.id) break
+        position++
+      }
+      if (position !== messages.length) continue
+      // 空投影可能属于区间也可能不属于；没有真实事务端点时不猜。
+      if (nodes[start - 1]?.message === null || nodes[end + 1]?.message === null) throw new Error('source span ambiguous')
+      matches.push(nodes.slice(start, end + 1).map(node => node.seq))
+      break
+    }
+  }
+  if (matches.length !== 1) throw new Error('source span unavailable or ambiguous')
+  const seqs = matches[0], measured = meter.measure(session).nodes
+  if (measured.length !== nodes.length || measured.some((node, index) => node.seq !== nodes[index].seq)) throw new Error('source token surface changed')
+  const selected = new Set(seqs)
+  const tokens = measured.filter(node => selected.has(node.seq)).reduce((total, node) => total + node.tokens, 0)
+  if (!Number.isFinite(tokens) || tokens <= 0) throw new Error('source token budget unavailable')
+  return { events, seqs, tokens }
+}
+
+export function createProvenanceCompaction(BasicClass, { sourceModuleId, isActive = () => true, signalOf = () => undefined, makeReference = makeSessionReference } = {}) {
+  return class ProvenanceCompaction extends BasicClass {
+    async summarize(input, agent, signal = signalOf(agent)) {
+      const check = () => {
+        signal?.throwIfAborted()
+        if (!isActive(agent)) throw new DOMException('context-provenance: compaction released', 'AbortError')
+      }
+      const warn = message => { try { this.ctx.logger?.warn?.('context-provenance: summary without reference (' + message + ')') } catch { /* 诊断不能使原本可用的压缩失败。 */ } }
+      check()
+      let snapshot
+      try { snapshot = sourceSnapshot(input, agent.session, this.ctx.tokenMeter) } catch (error) { warn(String(error?.message ?? error)) }
+      const result = await super.summarize(input, agent, signal)
+      check()
+      if (!snapshot) return result
+      try {
+        const reference = makeReference(sourceModuleId, agent.session.id, snapshot.events, snapshot.seqs)
+        const summary = [{ type: 'text', text: `[source: ${JSON.stringify(reference)}]\n` }, ...result.summary]
+        const tokens = this.ctx.tokenMeter.estimateMessage(framed(summary))
+        if (!Number.isFinite(tokens) || tokens >= snapshot.tokens) {
+          warn('reference exceeds shrink budget')
+          return result
+        }
+        return { ...result, summary }
+      } catch (error) {
+        warn(String(error?.message ?? error))
+        return result
+      }
+    }
+  }
+}