dsh-context-compression-improved 0.1.1 → 0.2.0

package/packages/selector/src/profiles.ts

@@ -0,0 +1,342 @@
+/** Public context-compression choices shared by the Host schema and browser selector. */
+export const COMPRESSION_PROFILES = [
+  'off',
+  'native',
+  'balanced',
+  'cache-strict',
+  'savings',
+  'adaptive',
+  'tokenpilot-inspired',
+  'custom',
+] as const
+
+/** One supported context-compression profile. */
+export type CompressionProfile = typeof COMPRESSION_PROFILES[number]
+
+/** Single canonical unit stored by a version-1 browser Custom document. */
+export type CustomCompressionUnit = 'tokens' | 'context-percent'
+
+/** Whether Custom History may routinely rewrite an already-sent prefix. */
+export type CustomPrefixPolicy = 'preserve' | 'pressure-break'
+
+/** Browser representation of one independently enabled Fresh or Aggregate budget. */
+export interface CustomCompressionBudget {
+  enabled: boolean
+  trigger: number
+  target: number
+}
+
+/** Legacy browser representation of the Custom History working set. */
+export interface LegacyCustomHistoryPolicy {
+  enabled: boolean
+  trigger: number
+  keepRecentTurns: number
+  keepRecent: number
+  minReclaim: number
+}
+
+/** Browser representation of Custom History tool-call and token-tail protection. */
+export interface CustomHistoryPolicy {
+  enabled: boolean
+  trigger: number
+  keepRecentToolCalls: number
+  keepRecentTokens: number
+  minReclaim: number
+}
+
+/** Browser representation of the Custom-only Experimental TailTrim gate. */
+export interface CustomTailTrimPolicy {
+  enabled: boolean
+  trigger: number
+}
+
+interface CustomCompressionPolicyCommon<HistoryPolicy> {
+  unit: CustomCompressionUnit
+  fresh: CustomCompressionBudget
+  aggregate: CustomCompressionBudget
+  history: HistoryPolicy
+  prefixPolicy: CustomPrefixPolicy
+}
+
+/** Legacy public Custom document; accepted and normalized before editing. */
+export interface CustomCompressionPolicyV1 extends CustomCompressionPolicyCommon<LegacyCustomHistoryPolicy> {
+  version: 1
+}
+
+/** Legacy Custom document with a default-disabled TailTrim stage. */
+export interface CustomCompressionPolicyV2 extends CustomCompressionPolicyCommon<LegacyCustomHistoryPolicy> {
+  version: 2
+  tailTrim: CustomTailTrimPolicy
+}
+
+/** Public Custom document with tool-call working-set protection. */
+export interface CustomCompressionPolicyV3 extends CustomCompressionPolicyCommon<CustomHistoryPolicy> {
+  version: 3
+  tailTrim: CustomTailTrimPolicy
+}
+
+/** Exact public Custom document accepted by the Host and browser boundary. */
+export type CustomCompressionPolicy = CustomCompressionPolicyV1 | CustomCompressionPolicyV2 | CustomCompressionPolicyV3
+
+/** Browser-safe mirror of the Host's Balanced-equivalent Custom default. */
+export const DEFAULT_CUSTOM_COMPRESSION_POLICY: CustomCompressionPolicyV3 = {
+  version: 3,
+  unit: 'tokens',
+  fresh: { enabled: true, trigger: 8_192, target: 3_072 },
+  aggregate: { enabled: true, trigger: 32_768, target: 12_288 },
+  history: {
+    enabled: true,
+    trigger: 500_000,
+    keepRecentToolCalls: 10,
+    keepRecentTokens: 64_000,
+    minReclaim: 96_000,
+  },
+  prefixPolicy: 'pressure-break',
+  tailTrim: { enabled: false, trigger: 700_000 },
+}
+
+/** User-tunable Auto Compact coordination preferences. */
+export interface AutoCompactSettings {
+  thresholdPercent: number
+}
+
+/**
+ * Orthogonal code-skeleton reducer gate, mirrored browser-safe from the
+ * runtime: independent of every profile, default off.
+ */
+export interface CodeSkeletonSettings {
+  enabled: boolean
+}
+
+/**
+ * Decode the persisted codeSkeleton section with exactly the runtime schema's
+ * strictness: absent means the lossless off default; present values must be a
+ * plain object carrying only a boolean `enabled`. Anything else is invalid,
+ * never silently coerced.
+ */
+export function decodeCodeSkeletonSettings(value: unknown): CodeSkeletonSettings | undefined {
+  if (value === undefined) return { enabled: false }
+  if (!isPlainRecord(value)) return undefined
+  const keys = Object.keys(value)
+  if (keys.length !== 1 || keys[0] !== 'enabled') return undefined
+  const enabled = (value as Record<string, unknown>).enabled
+  return typeof enabled === 'boolean' ? { enabled } : undefined
+}
+
+/** Browser-safe mirror of the runtime presetOptions section. */
+export interface PresetOptionsSettings {
+  readonly dedupeToolResults?: boolean
+  readonly summaryLocator?: boolean
+  readonly prefixStabilizer?: boolean
+  readonly readState?: boolean
+  readonly estimatorMode?: '' | 'host' | 'direct'
+  readonly estimatorProvider?: string
+  readonly estimatorModel?: string
+  readonly estimatorBaseUrl?: string
+  readonly estimatorApiKey?: string
+  readonly estimatorTimeoutMs?: number
+}
+
+/**
+ * Browser mirror of the runtime presetOptions section: absent inherits the
+ * preset defaults (decodes to `undefined`); present values must be a plain
+ * object carrying only the known keys with valid types.
+ */
+export function decodePresetOptionsSettings(value: unknown): PresetOptionsSettings | undefined {
+  if (value === undefined) return undefined
+  if (!isPlainRecord(value)) return undefined
+  const allowed = new Set([
+    'dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState', 'estimatorMode',
+    'estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey', 'estimatorTimeoutMs',
+  ])
+  if (Object.keys(value).some(key => !allowed.has(key))) return undefined
+  for (const key of ['dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState'] as const) {
+    const entry = value[key]
+    if (entry !== undefined && typeof entry !== 'boolean') return undefined
+  }
+  const estimatorMode = value.estimatorMode
+  if (estimatorMode !== undefined && estimatorMode !== '' && estimatorMode !== 'host' && estimatorMode !== 'direct') {
+    return undefined
+  }
+  for (const key of ['estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey'] as const) {
+    const entry = value[key]
+    if (entry !== undefined && typeof entry !== 'string') return undefined
+  }
+  const estimatorTimeoutMs = value.estimatorTimeoutMs
+  if (estimatorTimeoutMs !== undefined
+    && (typeof estimatorTimeoutMs !== 'number' || !Number.isSafeInteger(estimatorTimeoutMs)
+      || estimatorTimeoutMs < 100 || estimatorTimeoutMs > 60_000)) {
+    return undefined
+  }
+  const decoded: {
+    -readonly [K in keyof PresetOptionsSettings]: PresetOptionsSettings[K]
+  } = {}
+  if (value.dedupeToolResults !== undefined) decoded.dedupeToolResults = value.dedupeToolResults as boolean
+  if (value.summaryLocator !== undefined) decoded.summaryLocator = value.summaryLocator as boolean
+  if (value.prefixStabilizer !== undefined) decoded.prefixStabilizer = value.prefixStabilizer as boolean
+  if (value.readState !== undefined) decoded.readState = value.readState as boolean
+  if (estimatorMode !== undefined) decoded.estimatorMode = estimatorMode as '' | 'host' | 'direct'
+  if (value.estimatorProvider !== undefined) decoded.estimatorProvider = value.estimatorProvider as string
+  if (value.estimatorModel !== undefined) decoded.estimatorModel = value.estimatorModel as string
+  if (value.estimatorBaseUrl !== undefined) decoded.estimatorBaseUrl = value.estimatorBaseUrl as string
+  if (value.estimatorApiKey !== undefined) decoded.estimatorApiKey = value.estimatorApiKey as string
+  if (estimatorTimeoutMs !== undefined) decoded.estimatorTimeoutMs = estimatorTimeoutMs as number
+  return decoded
+}
+
+/**
+ * The one threshold contract shared by the UI, the persisted settings, and the
+ * runtime resolver; mirrored browser-safe from the runtime package.
+ */
+export const AUTO_COMPACT_THRESHOLD_LIMITS = Object.freeze({
+  min: 50,
+  max: 90,
+  step: 1,
+  default: 80,
+} as const)
+
+/** Narrow one unknown value to a valid Auto Compact threshold percent. */
+export function isValidAutoCompactThresholdPercent(value: unknown): value is number {
+  return typeof value === 'number'
+    && Number.isSafeInteger(value)
+    && value >= AUTO_COMPACT_THRESHOLD_LIMITS.min
+    && value <= AUTO_COMPACT_THRESHOLD_LIMITS.max
+}
+
+/** Accept JSON-object records while rejecting class instances and exotic prototypes. */
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value) as object | null
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * Decode the persisted autoCompact section with exactly the runtime schema's
+ * strictness: absent means the 80% default; present values must be a plain
+ * object carrying only a valid `thresholdPercent`. Anything else is invalid,
+ * never silently coerced.
+ */
+export function decodeAutoCompactSettings(value: unknown): AutoCompactSettings | undefined {
+  if (value === undefined) return { thresholdPercent: AUTO_COMPACT_THRESHOLD_LIMITS.default }
+  if (!isPlainRecord(value)) return undefined
+  const keys = Object.keys(value)
+  if (keys.length !== 1 || keys[0] !== 'thresholdPercent') return undefined
+  const thresholdPercent = (value as Record<string, unknown>).thresholdPercent
+  return isValidAutoCompactThresholdPercent(thresholdPercent)
+    ? { thresholdPercent }
+    : undefined
+}
+
+/** Durable settings section owned by this package. */
+export interface ContextCompressionSettings {
+  /** Default profile captured when each Session first reaches the pruner. */
+  profile: CompressionProfile
+  /** Complete canonical policy captured with `profile` when the runtime first observes a Session. */
+  custom: CustomCompressionPolicy
+  /** Auto Compact trigger captured with `profile` when the runtime first observes a Session. */
+  autoCompact: AutoCompactSettings
+  /** Code-skeleton reducer gate captured independently of `profile`. */
+  codeSkeleton: CodeSkeletonSettings
+  /** Optional tokenpilot-inspired sub-capability overrides (presence-validated only). */
+  presetOptions?: PresetOptionsSettings
+}
+
+/**
+ * Narrow an unknown settings value to a complete supported Custom policy.
+ * @param value - Candidate settings value received from the Host or edited locally.
+ * @returns Whether the value is a relation-valid Custom policy.
+ */
+export function isCustomCompressionPolicy(value: unknown): value is CustomCompressionPolicy {
+  if (!hasExactKeys(
+    value,
+    value !== null && typeof value === 'object' && 'version' in value && value.version === 1
+      ? ['version', 'unit', 'fresh', 'aggregate', 'history', 'prefixPolicy']
+      : ['version', 'unit', 'fresh', 'aggregate', 'history', 'prefixPolicy', 'tailTrim'],
+  )) return false
+  if ((value.version !== 1 && value.version !== 2 && value.version !== 3)
+    || (value.unit !== 'tokens' && value.unit !== 'context-percent')) return false
+  if (value.prefixPolicy !== 'preserve' && value.prefixPolicy !== 'pressure-break') return false
+  if (!isBudget(value.fresh) || !isBudget(value.aggregate)) return false
+  const modernHistory = value.version === 3
+  if (!hasExactKeys(
+    value.history,
+    modernHistory
+      ? ['enabled', 'trigger', 'keepRecentToolCalls', 'keepRecentTokens', 'minReclaim']
+      : ['enabled', 'trigger', 'keepRecentTurns', 'keepRecent', 'minReclaim'],
+  )) return false
+  if (typeof value.history.enabled !== 'boolean'
+    || typeof value.history.trigger !== 'number'
+    || typeof value.history.minReclaim !== 'number') return false
+  const recent = modernHistory
+    ? value.history.keepRecentTokens
+    : value.history.keepRecent
+  const calls = modernHistory ? value.history.keepRecentToolCalls : value.history.keepRecentTurns
+  if (typeof recent !== 'number'
+    || typeof calls !== 'number'
+    || !Number.isSafeInteger(calls)
+    || calls < 0) return false
+  let tailTrimTrigger: number | undefined
+  if (value.version !== 1) {
+    const tailTrim = value.tailTrim
+    if (!hasExactKeys(tailTrim, ['enabled', 'trigger'])
+      || typeof tailTrim.enabled !== 'boolean'
+      || typeof tailTrim.trigger !== 'number') return false
+    tailTrimTrigger = tailTrim.trigger
+  }
+  const measured = [
+    value.fresh.trigger, value.fresh.target,
+    value.aggregate.trigger, value.aggregate.target,
+    value.history.trigger, recent, value.history.minReclaim,
+    ...tailTrimTrigger === undefined ? [] : [tailTrimTrigger],
+  ]
+  if (!measured.every(entry => typeof entry === 'number' && Number.isFinite(entry))) return false
+  if (value.fresh.trigger <= 0 || value.fresh.target <= 0
+    || value.aggregate.trigger <= 0 || value.aggregate.target <= 0
+    || value.history.trigger <= 0 || recent < 0
+    || value.history.minReclaim <= 0
+    || (tailTrimTrigger !== undefined && tailTrimTrigger <= 0)) return false
+  if (value.unit === 'tokens' && !measured.every(Number.isSafeInteger)) return false
+  if (value.unit === 'context-percent' && !measured.every(entry => entry <= 100)) return false
+  return value.fresh.target < value.fresh.trigger
+    && value.aggregate.target < value.aggregate.trigger
+    && value.history.minReclaim <= value.history.trigger
+}
+
+function isBudget(value: unknown): value is CustomCompressionBudget {
+  return hasExactKeys(value, ['enabled', 'trigger', 'target'])
+    && typeof value.enabled === 'boolean'
+    && typeof value.trigger === 'number'
+    && typeof value.target === 'number'
+}
+
+/**
+ * Canonicalize one validated Custom document to version 3, mirroring the
+ * runtime's `canonicalizeCustomPolicy` exactly so the browser and runtime
+ * boundaries hand the SAME complete document to the UI and the policy
+ * resolver: legacy v1/v2 History working sets upgrade to the 10-call default,
+ * and a v1 document gains the default-disabled TailTrim stage.
+ */
+export function canonicalizeCustomPolicy(policy: CustomCompressionPolicy): CustomCompressionPolicyV3 {
+  if (policy.version === 3) return structuredClone(policy)
+  return {
+    version: 3,
+    unit: policy.unit,
+    fresh: structuredClone(policy.fresh),
+    aggregate: structuredClone(policy.aggregate),
+    history: {
+      enabled: policy.history.enabled,
+      trigger: policy.history.trigger,
+      keepRecentToolCalls: 10,
+      keepRecentTokens: policy.history.keepRecent,
+      minReclaim: policy.history.minReclaim,
+    },
+    prefixPolicy: policy.prefixPolicy,
+    tailTrim: policy.version === 1 ? { enabled: false, trigger: 700_000 } : structuredClone(policy.tailTrim),
+  }
+}
+
+function hasExactKeys(value: unknown, expected: readonly string[]): value is Record<string, unknown> {
+  if (!isPlainRecord(value)) return false
+  const keys = Object.keys(value)
+  return keys.length === expected.length && keys.every(key => expected.includes(key))
+}

package/packages/selector/src/pruner/content.ts

@@ -0,0 +1,188 @@
+/**
+ * Pure content-analysis functions extracted from ToolResultPruner.
+ *
+ * Every function here has ZERO `this` dependency — they receive all inputs
+ * as explicit arguments. Grouped by natural cohesion (content blocks →
+ * token counting → recovery helpers).
+ *
+ * @module dsh-context-compression-improved/pruner/content
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type {
+  CompactionTokenView,
+  ProviderMeasurementKey,
+  TokenCount,
+} from '../runtime/measurement.ts'
+import { countExactCanonicalTextFields } from '../runtime/token-count.ts'
+import { codePointLength, PRUNE_MARKER } from '../runtime/config.ts'
+import type { PrunedEntry, PruneResult } from '../runtime/types.ts'
+import { RICH_BLOCK_PRESSURE_COST } from './tuning.ts'
+
+// ── Content-block predicates ────────────────────────────────────────────
+
+function onlyTextBlock(blocks: readonly ContentBlock[]): Extract<ContentBlock, { type: 'text' }> | null {
+  return blocks.length === 1 && blocks[0]?.type === 'text' ? blocks[0] : null
+}
+
+function onlyTextBlocks(blocks: readonly ContentBlock[]): readonly Extract<ContentBlock, { type: 'text' }>[] | null {
+  return blocks.every((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
+    ? blocks
+    : null
+}
+
+// ── Token counting ──────────────────────────────────────────────────────
+
+function countToolContent(blocks: readonly ContentBlock[], view: CompactionTokenView): TokenCount {
+  const text = onlyTextBlocks(blocks)
+  if (text === null) return unavailableCount('tool result contains unsupported rich content')
+  return countExactCanonicalTextFields(
+    text.map(block => block.text),
+    candidate => view.countCanonicalText(candidate),
+    'tool result replacement',
+  )
+}
+
+function exactTokens(count: TokenCount): number | undefined {
+  return count.kind === 'exact-tokenizer' ? count.tokens : undefined
+}
+
+// ── Provider measurement key comparison ─────────────────────────────────
+
+function sameProviderMeasurementKey(
+  left: Readonly<ProviderMeasurementKey>,
+  right: Readonly<ProviderMeasurementKey>,
+): boolean {
+  return left.provider === right.provider
+    && left.baseUrlClass === right.baseUrlClass
+    && left.apiRoute === right.apiRoute
+    && left.modelId === right.modelId
+    && left.requestTemplateRevision === right.requestTemplateRevision
+    && left.tokenizerRevision === right.tokenizerRevision
+    && left.modality === right.modality
+}
+
+// ── Token helpers ───────────────────────────────────────────────────────
+
+function unavailableCount(reason: string): TokenCount {
+  return Object.freeze({ kind: 'unavailable', reason })
+}
+
+// ── Recovery markers ────────────────────────────────────────────────────
+
+function recoveryMarker(sourceRef: string, label: string): string {
+  return `\n\n[... ${label}; source=${sourceRef}; use context_compression_retrieve if needed ...]\n\n`
+}
+
+// ── Content measurement ─────────────────────────────────────────────────
+
+/**
+ * Measure text content in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content to measure.
+ * @returns total Unicode code points across text blocks.
+ */
+function measureContent(blocks: readonly ContentBlock[]): number {
+  let chars = 0
+  for (const block of blocks) {
+    if (block.type === 'text') chars += codePointLength(block.text)
+  }
+  return chars
+}
+
+function pressureCost(blocks: readonly ContentBlock[]): number {
+  let cost = 0
+  for (const block of blocks) {
+    switch (block.type) {
+      case 'text':
+      case 'reasoning':
+        cost += codePointLength(block.text)
+        break
+      case 'tool-call':
+        cost += RICH_BLOCK_PRESSURE_COST
+          + codePointLength(block.name)
+          + codePointLength(block.arguments)
+        break
+      case 'tool-result':
+        cost += RICH_BLOCK_PRESSURE_COST + pressureCost(block.content)
+        break
+      default: {
+        // ContentBlockMap is merge-extensible. Unknown model-visible blocks
+        // scale with their durable JSON payload instead of receiving a fixed
+        // token that a large provider block could bypass.
+        const serialized = JSON.stringify(block)
+        cost += Math.max(RICH_BLOCK_PRESSURE_COST, codePointLength(serialized))
+      }
+    }
+  }
+  return cost
+}
+
+// ── Native content pruning ──────────────────────────────────────────────
+
+function nativePruneContent(
+  blocks: readonly ContentBlock[],
+  thresholdChars: number,
+  headChars: number,
+  tailChars: number,
+  marker: string = PRUNE_MARKER,
+): ContentBlock[] | null {
+  const totalChars = measureContent(blocks)
+  if (totalChars <= thresholdChars) return null
+  const markerChars = codePointLength(marker)
+  const safeHead = Math.max(0, Math.min(headChars, thresholdChars - markerChars))
+  const safeTail = Math.max(0, Math.min(tailChars, thresholdChars - markerChars - safeHead))
+  const removedStart = safeHead
+  const removedEnd = totalChars - safeTail
+  const pruned: ContentBlock[] = []
+  let consumed = 0
+  let markerInserted = false
+  for (const block of blocks) {
+    if (block.type !== 'text') {
+      pruned.push(block)
+      continue
+    }
+    const points = Array.from(block.text)
+    const blockStart = consumed
+    const blockEnd = blockStart + points.length
+    const headEnd = Math.min(points.length, Math.max(0, removedStart - blockStart))
+    const tailStart = Math.min(points.length, Math.max(0, removedEnd - blockStart))
+    const intersectsRemoved = blockStart < removedEnd && blockEnd > removedStart
+    const insertion = intersectsRemoved && !markerInserted ? marker : ''
+    if (insertion !== '') markerInserted = true
+    const text = points.slice(0, headEnd).join('') + insertion + points.slice(tailStart).join('')
+    if (text !== '') pruned.push({ ...block, text })
+    consumed = blockEnd
+  }
+  if (!markerInserted) return null
+  const charsAfter = measureContent(pruned)
+  return charsAfter <= thresholdChars && charsAfter < totalChars ? pruned : null
+}
+
+// ── Result aggregation ──────────────────────────────────────────────────
+
+function summarize(entries: readonly PrunedEntry[]): PruneResult {
+  return {
+    pruned: entries,
+    charsRemoved: entries.reduce((sum, entry) => sum + entry.charsBefore - entry.charsAfter, 0),
+    tokensRemoved: entries.reduce((sum, entry) => sum + entry.tokensBefore - entry.tokensAfter, 0),
+  }
+}
+
+function emptyResult(): PruneResult {
+  return { pruned: [], charsRemoved: 0, tokensRemoved: 0 }
+}
+
+export {
+  onlyTextBlock,
+  onlyTextBlocks,
+  countToolContent,
+  exactTokens,
+  sameProviderMeasurementKey,
+  unavailableCount,
+  recoveryMarker,
+  summarize,
+  emptyResult,
+  measureContent,
+  pressureCost,
+  nativePruneContent,
+}

package/packages/selector/src/pruner/session.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure session-scanning functions extracted from ToolResultPruner.
+ *
+ * Every function here has ZERO `this` dependency — they receive all inputs
+ * as explicit arguments and only read session events.
+ *
+ * @module dsh-context-compression-improved/pruner/session
+ */
+
+import type { Session } from '@deepseek-ai/dsh-session'
+import { sessionEvents } from '../runtime/session-events.ts'
+import { deepSeekV4TokenizerForModel } from '../deepseek-v4-tokenizer.ts'
+import type { SnapshotCandidate, PlannedReplacement, HistoryPlanOutcome } from './types.ts'
+
+/** Check whether the session currently has an open (unterminated) turn. */
+function hasOpenTurn(session: Session): boolean {
+  let open = false
+  for (const event of sessionEvents(session)) {
+    if (event.type === 'turn/start') open = true
+    else if (event.type === 'turn/end') open = false
+  }
+  return open
+}
+
+/** Walk the tool-result source chain to find the root result seq. */
+function rootToolResultSeq(session: Session, seq: number): number {
+  const events = sessionEvents(session)
+  let current = seq
+  const seen = new Set<number>()
+  while (!seen.has(current)) {
+    seen.add(current)
+    const event = events[current]
+    if (event?.type !== 'tool/result' || typeof event.surfaceOp !== 'object') return current
+    const previous = event.sourceEventSeqs?.[0]
+    if (previous === undefined) return current
+    current = previous
+  }
+  return seq
+}
+
+/** Build a session:// event reference string for a given seq. */
+function sourceRef(session: Session, seq: number): string {
+  return `session://${session.id}/event/${String(seq)}`
+}
+
+/** Find the latest completed step number for a given turn. */
+function latestCompletedToolStep(session: Session, turn: number): number | undefined {
+  let latest: number | undefined
+  for (const event of sessionEvents(session)) {
+    if (event.type === 'step/end' && event.data.turn === turn) latest = event.data.step
+  }
+  return latest
+}
+
+/** Routed provider/model when the durable request header names one route. */
+function routeAuditFact(session: Session): { provider: string, model: string } | undefined {
+  const header = session.requestHeader()?.config
+  if (header === undefined || header.provider.length === 0 || header.model.length === 0) return undefined
+  return { provider: header.provider, model: header.model }
+}
+
+/** Bundled tokenizer identity for one route, when the route is eligible. */
+function tokenizerAuditFact(route: { provider: string, model: string }): { tokenizer: { repository: string, revision: string } } {
+  // Reuse the measurement eligibility boundary: a DeepSeek model id routed
+  // through another provider never used the bundled tokenizer.
+  const eligible = route.provider === 'deepseek' || route.provider === 'deepseek-official'
+  const identity = eligible ? deepSeekV4TokenizerForModel(route.model)?.countText('') : undefined
+  if (identity?.kind === 'exact-tokenizer') {
+    return { tokenizer: { repository: identity.tokenizerId, revision: identity.tokenizerRevision } }
+  }
+  return { tokenizer: { repository: 'unavailable', revision: 'unavailable' } }
+}
+
+/** Check whether a snapshot candidate represents an error result. */
+function isError(candidate: SnapshotCandidate): boolean {
+  const result = candidate.event.data.message.content[0]
+  return result.isError === true || candidate.event.data.error !== undefined
+}
+
+/** Wrap a plan list into a HistoryPlanOutcome. */
+function historyOutcome(plans: readonly PlannedReplacement[]): HistoryPlanOutcome {
+  return { kind: 'planned', plans: [...plans] }
+}
+
+export {
+  hasOpenTurn,
+  rootToolResultSeq,
+  sourceRef,
+  latestCompletedToolStep,
+  routeAuditFact,
+  tokenizerAuditFact,
+  isError,
+  historyOutcome,
+}

package/packages/selector/src/pruner/state.ts

@@ -0,0 +1,43 @@
+/**
+ * Consolidated per-session mutable state for {@link ToolResultPruner}.
+ *
+ * Every field is a WeakMap keyed by Session, keeping the service
+ * stateless across sessions and safe under GC.
+ */
+
+import type { Session } from '@deepseek-ai/dsh-session'
+import type { DedupeTable } from '../runtime/tokenpilot/dedup.ts'
+import type { EstimatorFailures } from '../runtime/tokenpilot/estimator.ts'
+import type {
+  ContextCompressionSettings,
+  ResolvedConfig,
+} from '../runtime/types.ts'
+
+/** Mutable per-session state bag used inside {@link ToolResultPruner}. */
+export interface PrunerState {
+  /** Resolved immutable deployment configuration. */
+  readonly config: ResolvedConfig
+
+  /** Complete canonical setting document frozen when each Session first reaches this root service. */
+  readonly sessionSettings: WeakMap<Session, ContextCompressionSettings>
+  /** Original result seqs whose first-exposure KEEP/REDUCE decision has committed. */
+  readonly firstExposure: WeakMap<Session, Set<number>>
+  /** Result seqs permanently exempt from further reduction (recovery outputs and registered equivalents). */
+  readonly recoveryExemptions: WeakMap<Session, Set<number>>
+  /** Per-session canonical-content hash index backing tokenpilot-inspired dedupe. */
+  readonly dedupeTables: WeakMap<Session, DedupeTable>
+  /** Advisory estimator verdicts consumed by the read-state classification. */
+  readonly estimatorVerdicts: WeakMap<Session, Map<number, boolean>>
+  /** Per-session estimator failure backoff state. */
+  readonly estimatorFailures: WeakMap<Session, EstimatorFailures>
+  /** Runtime prerequisite warnings deduplicated per Session and failure key. */
+  readonly warnedFailures: WeakMap<Session, Set<string>>
+  /** Last Adaptive postflight attempt emitted per Session; keeps diagnostics bounded and independent. */
+  readonly postflightDiagnostics: WeakMap<Session, string>
+  /** Current pre-step chain identity, shared by this producer and downstream compaction-basic. */
+  readonly activeRequestBoundaries: WeakMap<Session, object>
+  /** Boundary identity that already attempted one fully preflighted TailTrim publication. */
+  readonly tailTrimBoundaryAttempts: WeakMap<Session, object>
+  /** Last effective policy audit key emitted for each Session. */
+  readonly policyResolutionAudits: WeakMap<Session, string>
+}