dsh-context-compression-improved 0.4.0 → 0.5.0

package/packages/selector/src/runtime/tokenpilot/advisor.ts

@@ -0,0 +1,419 @@
+/**
+ * Advisory relevance advisor: LLM relevance statistics and suggestions bound
+ * to the session todolist.
+ *
+ * The advisor is NOT a reviewer or gate. Every output — tail-task summaries,
+ * per-candidate relevance scores, the prefix-decay figure, recertification
+ * marks — is observational: it must never suppress, delay, or rewrite any
+ * reduction that would land, and nothing here is consulted by any decision
+ * path this round. Failures are fail-open; every call is fire-and-forget from
+ * the turn-stopping boundary.
+ *
+ * Task semantics come from the most recent `todo/write` session event
+ * (defensively parsed — the payload carries no public type), falling back to
+ * recent user/message text when no todolist exists.
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { charsForTokens, codePointLength } from '../config.ts'
+import type { CompressionProfile } from '../types.ts'
+import type { AdvisorOutcomeAuditRecord } from '../audit.ts'
+import {
+  getAdvisorState,
+  invalidateOnTaskChange,
+  recordRecertified,
+  recordScore,
+  type AdvisorState,
+} from './advisor-state.ts'
+import type { SideChannel } from './sidechannel.ts'
+import {
+  buildAdvisorScoringSystemPrompt,
+  buildAdvisorScoringUserPrompt,
+  buildAdvisorSummarySystemPrompt,
+  buildAdvisorSummaryUserPrompt,
+  parseAdvisorScores,
+  parseAdvisorSummary,
+} from './advisor-prompt.ts'
+
+/** Character cap for the recent-text fallback and the tail-text summary input. */
+export const TAIL_TEXT_CHAR_BUDGET = 4_000
+/** Score the advisor assigns to candidates it has no answer for. */
+const NEUTRAL_RELEVANCE = 0.5
+
+/** Task semantics harvested from the session log, bound to the todolist. */
+export interface TaskSemantics {
+  /** `todos`: structured todo/write payload; `raw-todo`: degraded JSON string; `messages`: recent user text. */
+  readonly source: 'todos' | 'raw-todo' | 'messages'
+  /** Stable version token of the task semantics (scores/summaries invalidate on change). */
+  readonly todoVersion: string
+  /** Human-readable task description fed to the summary and scoring prompts. */
+  readonly taskText: string
+}
+
+/** Minimal candidate face the advisor needs; satisfied by SnapshotCandidate. */
+export interface AdvisorCandidate {
+  readonly seq: number
+  readonly characterPressure: number
+  /** Short content sample for the scoring prompt (tool-call name + text head). */
+  readonly preview: string
+}
+
+/** One scoring-pass candidate with its local keyword-overlap prescreen rank. */
+interface ScoredCandidateView extends AdvisorCandidate {
+  readonly overlap: number
+}
+
+/** Deterministic djb2-derived hex digest for task-semantics versioning. */
+function versionDigest(text: string): string {
+  let hash = 5381
+  for (let index = 0; index < text.length; index += 1) {
+    hash = ((hash * 33) ^ text.charCodeAt(index)) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0')
+}
+
+/** Truncate on the character basis (Unicode code points), never UTF-16 units. */
+function truncateChars(text: string, budget: number): string {
+  if (codePointLength(text) <= budget) return text
+  return Array.from(text).slice(0, budget).join('')
+}
+
+/** Character cap of one candidate preview line offered to the scoring prompt. */
+const PREVIEW_CHAR_BUDGET = 200
+
+/**
+ * One candidate face for the scoring prompt: tool-call name plus the head of
+ * the result text. Pure and shape-defensive.
+ */
+export function advisorCandidatePreview(callName: string, blocks: unknown): string {
+  const text = textBlocks(blocks)
+  return truncateChars(`${callName} ${text}`.trim(), PREVIEW_CHAR_BUDGET)
+}
+
+/**
+ * Collect the recent assistant narration tail (bounded, oldest-first join) as
+ * summary-prompt context. Pure.
+ */
+export function collectTailText(events: readonly SessionEvent[], budget: number = TAIL_TEXT_CHAR_BUDGET): string {
+  const parts: string[] = []
+  let size = 0
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (event?.type !== 'assistant/message') continue
+    const text = textBlocks(event.data).trim()
+    if (text.length === 0) continue
+    parts.unshift(text)
+    size += codePointLength(text)
+    if (size >= budget) break
+  }
+  return truncateChars(parts.join('\n'), budget)
+}
+
+function textBlocks(data: unknown): string {
+  const content = (data as { content?: { type?: unknown, text?: unknown }[] } | undefined)?.content
+  if (!Array.isArray(content)) return ''
+  const parts: string[] = []
+  for (const block of content) {
+    if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+  }
+  return parts.join('\n')
+}
+
+/** Structured probe of one `todo/write` payload: the list of task strings, or undefined. */
+function extractTodoItems(data: unknown): string[] | undefined {
+  const todos = (data as { todos?: unknown } | undefined)?.todos
+  const list = Array.isArray(todos) ? todos : Array.isArray(data) ? data : undefined
+  if (list === undefined || list.length === 0) return undefined
+  const items: string[] = []
+  for (const entry of list) {
+    if (typeof entry === 'string') {
+      if (entry.trim().length > 0) items.push(entry.trim())
+      continue
+    }
+    if (entry !== null && typeof entry === 'object') {
+      const record = entry as Record<string, unknown>
+      const text = [record.content, record.text, record.title, record.name]
+        .find(candidate => typeof candidate === 'string' && candidate.trim().length > 0)
+      if (typeof text === 'string') {
+        items.push(text.trim())
+        continue
+      }
+      // Structured shape the advisor does not recognize: keep the item visible
+      // as its raw JSON so the LLM still sees the todolist instead of nothing.
+      items.push(JSON.stringify(record))
+    }
+  }
+  return items.length > 0 ? items : undefined
+}
+
+/**
+ * Harvest task semantics for the summary/scoring prompts: the most recent
+ * `todo/write` event (structured probe first, then the raw JSON string),
+ * falling back to recent user/message text. Pure — log in, semantics out.
+ */
+export function collectTaskSemantics(events: readonly SessionEvent[]): TaskSemantics | undefined {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    // `todo/write` is plugin-merged into the runtime event vocabulary but not
+    // the static SessionEventMap union, so the probe compares widened types.
+    if (event === undefined || (event.type as string) !== 'todo/write') continue
+    const data: unknown = (event as { data?: unknown }).data
+    const items = extractTodoItems(data)
+    if (items !== undefined) {
+      const taskText = truncateChars(items.join('\n'), TAIL_TEXT_CHAR_BUDGET)
+      return { source: 'todos', todoVersion: versionDigest(taskText), taskText }
+    }
+    const raw = truncateChars(JSON.stringify(event.data) ?? '', TAIL_TEXT_CHAR_BUDGET)
+    if (raw.length > 2) {
+      return { source: 'raw-todo', todoVersion: versionDigest(raw), taskText: raw }
+    }
+  }
+  // No usable todolist: fall back to the most recent user/message text.
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (event?.type !== 'user/message') continue
+    const text = truncateChars(textBlocks(event.data).trim(), TAIL_TEXT_CHAR_BUDGET)
+    if (text.length === 0) continue
+    return { source: 'messages', todoVersion: versionDigest(text), taskText: text }
+  }
+  return undefined
+}
+
+/**
+ * Prefix-decay figure: 1 minus the character-pressure-weighted mean relevance
+ * of the prefix candidates. Unscored candidates count as neutral 0.5. Pure,
+ * deterministic, no LLM and no I/O.
+ */
+export function prefixDecay(
+  candidates: readonly { readonly seq: number, readonly characterPressure: number }[],
+  scores: ReadonlyMap<number, { readonly score: number }>,
+): { readonly decay: number, readonly weightedChars: number } {
+  let totalWeight = 0
+  let weightedRelevance = 0
+  for (const candidate of candidates) {
+    const weight = candidate.characterPressure > 0 ? candidate.characterPressure : 0
+    if (weight === 0) continue
+    totalWeight += weight
+    weightedRelevance += weight * (scores.get(candidate.seq)?.score ?? NEUTRAL_RELEVANCE)
+  }
+  if (totalWeight === 0) return { decay: 0, weightedChars: 0 }
+  return {
+    decay: 1 - weightedRelevance / totalWeight,
+    weightedChars: totalWeight,
+  }
+}
+
+/** Lowercase word tokens used by the local keyword-overlap prescreen. */
+function keywordsOf(text: string): Set<string> {
+  const matches = text.toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) ?? []
+  return new Set(matches)
+}
+
+function overlapCount(left: ReadonlySet<string>, right: ReadonlySet<string>): number {
+  let count = 0
+  for (const token of right) {
+    if (left.has(token)) count += 1
+  }
+  return count
+}
+
+/**
+ * Incremental scoring selection: candidates newer than the watermark whose
+ * character pressure reaches the token-named floor, ranked by local keyword
+ * overlap with the task semantics and cut at the sample limit. When the task
+ * semantics changed, the watermark is ignored so every eligible candidate can
+ * rescore. Pure.
+ */
+export function selectScoringCandidates(
+  candidates: readonly AdvisorCandidate[],
+  state: Pick<AdvisorState, 'watermarkSeq'>,
+  input: {
+    readonly taskKeywords: ReadonlySet<string>
+    readonly minChars: number
+    readonly sampleLimit: number
+    readonly taskChanged: boolean
+  },
+): AdvisorCandidate[] {
+  const eligible: ScoredCandidateView[] = []
+  for (const candidate of candidates) {
+    if (!input.taskChanged && candidate.seq <= state.watermarkSeq) continue
+    if (candidate.characterPressure < input.minChars) continue
+    eligible.push({
+      ...candidate,
+      overlap: overlapCount(input.taskKeywords, keywordsOf(candidate.preview)),
+    })
+  }
+  eligible.sort((left, right) => right.overlap - left.overlap || right.characterPressure - left.characterPressure)
+  return eligible.slice(0, input.sampleLimit).map(({ overlap: _overlap, ...candidate }) => candidate)
+}
+
+/** Advisor inputs the pruner owns; the advisor never reaches into pruner state. */
+export interface AdvisorPassInput {
+  readonly profile: CompressionProfile
+  readonly sessionId: string
+  readonly turn: number
+  readonly candidates: readonly AdvisorCandidate[]
+  readonly task: TaskSemantics | undefined
+  readonly advisor: {
+    readonly refreshTurns: number
+    readonly scoreThreshold: number
+    readonly sampleLimit: number
+    readonly minTokens: number
+  }
+  /** Tail assistant text offered to the summary prompt (already char-bounded). */
+  readonly tailText: string
+  readonly signal: AbortSignal
+}
+
+/** One ask-shaped LLM channel; satisfied by SideChannel.ask. */
+export type AdvisorChannel = Pick<SideChannel, 'ask' | 'identity'>
+
+export interface AdvisorPassOutcome {
+  readonly decay: number
+  readonly weightedChars: number
+  readonly sampled: number
+}
+
+function advisorAudit(
+  input: AdvisorPassInput,
+  phase: AdvisorOutcomeAuditRecord['phase'],
+  fields: Partial<AdvisorOutcomeAuditRecord> & { ok: boolean, latencyMs: number },
+): AdvisorOutcomeAuditRecord {
+  return {
+    schemaVersion: 1,
+    kind: 'advisor-outcome',
+    sessionId: input.sessionId,
+    phase,
+    turnIndex: input.turn,
+    ...fields,
+  }
+}
+
+/**
+ * One full advisor pass: summary refresh (todo change or every refreshTurns),
+ * incremental batch scoring with recertification marks, then the decay
+ * figure. State is written only on success; any failure leaves state
+ * untouched, emits ok:false audits with reason codes, and never throws.
+ */
+export async function runAdvisorPass(
+  state: AdvisorState,
+  channel: AdvisorChannel,
+  emit: (record: AdvisorOutcomeAuditRecord) => void,
+  input: AdvisorPassInput,
+): Promise<AdvisorPassOutcome | undefined> {
+  if (input.task === undefined) return undefined
+  const taskChanged = invalidateOnTaskChange(state, input.task.todoVersion)
+  const turn = input.turn
+  const needSummary = state.summary === undefined || turn - state.lastSummaryTurn >= input.advisor.refreshTurns
+
+  // 1. Tail-task summary: bound to the todolist, refreshed on change or interval.
+  if (needSummary) {
+    const summaryStarted = Date.now()
+    const summaryText = await channel.ask({
+      system: buildAdvisorSummarySystemPrompt(),
+      user: buildAdvisorSummaryUserPrompt(input.task.taskText, input.tailText),
+      signal: input.signal,
+    })
+    const summaryLatencyMs = Date.now() - summaryStarted
+    const summary = input.signal.aborted ? undefined : parseAdvisorSummary(summaryText)
+    if (summary === undefined) {
+      emit(advisorAudit(input, 'summary', {
+        ok: false,
+        latencyMs: summaryLatencyMs,
+        ...(input.signal.aborted
+          ? { reason: 'aborted' }
+          : summaryText === undefined ? { reason: 'channel-empty' } : { reason: 'parse-failed' }),
+      }))
+      return undefined
+    }
+    state.summary = { ...summary, todoVersion: input.task.todoVersion, turn }
+    state.lastSummaryTurn = turn
+    emit(advisorAudit(input, 'summary', { ok: true, latencyMs: summaryLatencyMs }))
+  }
+
+  const summary = state.summary
+  if (summary === undefined) return undefined
+
+  // 2. Incremental batch scoring: prescreened candidates, one LLM call.
+  const sampled = selectScoringCandidates(input.candidates, state, {
+    taskKeywords: keywordsOf(`${input.task.taskText}\n${summary.keywords.join(' ')}`),
+    minChars: charsForTokens(input.advisor.minTokens),
+    sampleLimit: input.advisor.sampleLimit,
+    taskChanged,
+  })
+    let scored = 0
+    let highestScored = 0
+    if (sampled.length > 0) {
+    const scoringStarted = Date.now()
+    const scoresText = await channel.ask({
+      system: buildAdvisorScoringSystemPrompt(),
+      user: buildAdvisorScoringUserPrompt(input.task.taskText, summary.activeSubtasks, sampled),
+      signal: input.signal,
+    })
+    const scoringLatencyMs = Date.now() - scoringStarted
+    const scores = input.signal.aborted ? undefined : parseAdvisorScores(scoresText, new Set(sampled.map(item => item.seq)))
+    if (scores === undefined || scores.size === 0) {
+      emit(advisorAudit(input, 'scoring', {
+        ok: false,
+        sampledCount: sampled.length,
+        latencyMs: scoringLatencyMs,
+        ...(input.signal.aborted
+          ? { reason: 'aborted' }
+          : scoresText === undefined ? { reason: 'channel-empty' } : { reason: 'parse-failed' }),
+      }))
+      return undefined
+    }
+    for (const candidate of sampled) {
+      const answer = scores.get(candidate.seq)
+      if (answer === undefined) continue
+      recordScore(state, candidate.seq, { score: answer.score, turn })
+      scored += 1
+      if (candidate.seq > highestScored) highestScored = candidate.seq
+      // R5: low-relevance segments are LLM-recertified as suggestions only —
+      // nothing consumes the marks this round, and the caller is expected to
+      // have filtered protected candidates out of `candidates`.
+      if (answer.score < input.advisor.scoreThreshold) recordRecertified(state, candidate.seq, turn)
+    }
+    emit(advisorAudit(input, 'scoring', { ok: true, sampledCount: sampled.length, latencyMs: scoringLatencyMs }))
+    // The watermark only moves past candidates that actually received a
+    // score: rows the channel dropped stay eligible so a later pass can
+    // rescore them instead of silently losing them behind the cut.
+    if (highestScored > state.watermarkSeq) state.watermarkSeq = highestScored
+  }
+
+  // 3. Decay figure over the whole prefix: local, always emitted on a pass
+  //    that got this far (even with zero samples this round). Stored on the
+  //    state so the report route serves the exact same figure (J3).
+  const decay = prefixDecay(input.candidates, state.scores)
+  state.lastDecay = { decay: decay.decay, weightedChars: decay.weightedChars, turn }
+  emit(advisorAudit(input, 'decay', {
+    ok: true,
+    sampledCount: scored,
+    decay: decay.decay,
+    weightedChars: decay.weightedChars,
+    latencyMs: 0,
+  }))
+  return { decay: decay.decay, weightedChars: decay.weightedChars, sampled: sampled.length }
+}
+
+/**
+ * Convenience entry used by the pruner: fetch-or-create the session state and
+ * run one pass against it.
+ */
+export async function runSessionAdvisorPass(
+  session: Parameters<typeof getAdvisorState>[0],
+  channel: AdvisorChannel,
+  emit: (record: AdvisorOutcomeAuditRecord) => void,
+  input: Omit<AdvisorPassInput, 'sessionId'> & { readonly sessionId?: string },
+): Promise<AdvisorPassOutcome | undefined> {
+  const state = getAdvisorState(session)
+  if (state.inFlight) return undefined
+  state.inFlight = true
+  try {
+    return await runAdvisorPass(state, channel, emit, {
+      ...input,
+      sessionId: input.sessionId ?? String(session.id),
+    })
+  } finally {
+    state.inFlight = false
+  }
+}

package/packages/selector/src/runtime/tokenpilot/sidechannel.ts

@@ -49,22 +49,37 @@ export interface SideChannelRequest {
 
 /** One bound side channel. `ask` resolves `undefined` on ANY failure. */
 export class SideChannel {
+  /**
+   * @param overrides - per-consumer overrides of the estimator-named options.
+   * The estimator itself never passes them (byte-identical behavior); the
+   * advisory advisor passes its own mode/timeout/output budget so both
+   * consumers share one transport without sharing one configuration.
+   */
   constructor(
     private readonly ctx: Context,
     private readonly options: PresetOptionsSettings,
+    private readonly overrides?: {
+      readonly mode?: '' | 'host' | 'direct'
+      readonly timeoutMs?: number
+      readonly maxTokens?: number
+    },
   ) {}
 
+  private get mode(): '' | 'host' | 'direct' {
+    return this.overrides?.mode ?? this.options.estimatorMode ?? ''
+  }
+
   get enabled(): boolean {
-    return this.options.estimatorMode === 'host' || this.options.estimatorMode === 'direct'
+    return this.mode === 'host' || this.mode === 'direct'
   }
 
   async ask(request: SideChannelRequest): Promise<string | undefined> {
-    const timeoutMs = this.options.estimatorTimeoutMs ?? 3_000
+    const timeoutMs = this.overrides?.timeoutMs ?? this.options.estimatorTimeoutMs ?? 3_000
     const timeout = AbortSignal.timeout(timeoutMs)
     const signal = typeof AbortSignal.any === 'function' ? AbortSignal.any([request.signal, timeout]) : timeout
     try {
-      if (this.options.estimatorMode === 'host') return await this.askHost(request.system, request.user, signal)
-      if (this.options.estimatorMode === 'direct') return await this.askDirect(request.system, request.user, signal)
+      if (this.mode === 'host') return await this.askHost(request.system, request.user, signal)
+      if (this.mode === 'direct') return await this.askDirect(request.system, request.user, signal)
       return undefined
     } catch {
       return undefined
@@ -79,16 +94,16 @@ export class SideChannel {
       ok: text !== undefined,
       latencyMs: Date.now() - now,
       ...this.identity() !== undefined ? { channel: this.identity()! } : {},
-      ...(text === undefined ? { reason: 'channel returned no content (timeout, non-2xx, parse failure, or reasoning ate the 256-token budget)' } : {}),
+      ...(text === undefined ? { reason: 'channel returned no content (timeout, non-2xx, parse failure, or reasoning ate the output-token budget)' } : {}),
     }
     return { ...(text === undefined ? {} : { text }), audit }
   }
 
   identity(): string | undefined {
-    if (this.options.estimatorMode === 'direct') {
+    if (this.mode === 'direct') {
       return `direct:${this.options.estimatorModel ?? ''}`
     }
-    if (this.options.estimatorMode === 'host') {
+    if (this.mode === 'host') {
       const route = this.resolveHostRoute()
       return route === undefined ? 'host' : `host:${route.provider}/${route.model}`
     }
@@ -137,7 +152,7 @@ export class SideChannel {
       system,
       temperature: 0,
       reasoningEffort: 'off',
-      maxTokens: 256,
+      maxTokens: this.overrides?.maxTokens ?? 256,
       signal,
     })
     for await (const chunk of stream) {
@@ -172,7 +187,7 @@ export class SideChannel {
           { role: 'user', content: user },
         ],
         temperature: 0,
-        max_tokens: 256,
+        max_tokens: this.overrides?.maxTokens ?? 256,
       }),
       signal,
     })

package/packages/selector/src/runtime/types.ts

@@ -71,6 +71,20 @@ export interface PresetOptions {
   readonly readState: boolean
   /** Optional estimator channel; `''` keeps every estimator consumer on rule-only fallbacks (E1/E2). */
   readonly estimator: { readonly mode: '' | 'host' | 'direct' }
+  /**
+   * Advisory relevance advisor: statistics and suggestions only — every output
+   * (summaries, scores, decay, recertification) is observational and must never
+   * suppress, delay, or rewrite any reduction that would land. `''` (the
+   * default) keeps the advisor fully off.
+   */
+  readonly advisor: {
+    readonly mode: '' | 'host' | 'direct'
+    readonly timeoutMs: number
+    readonly refreshTurns: number
+    readonly scoreThreshold: number
+    readonly sampleLimit: number
+    readonly minTokens: number
+  }
   /**
    * Human-gated review pipeline (beta): edge/high-impact candidates queue for
    * manual approval and execute in one merged batch at the next turn boundary
@@ -155,6 +169,13 @@ export interface PresetOptionsSettings {
   readonly estimatorBaseUrl?: string
   readonly estimatorApiKey?: string
   readonly estimatorTimeoutMs?: number
+  /** Advisory advisor channel; `''` (the default) keeps the advisor off. */
+  readonly advisorMode?: '' | 'host' | 'direct'
+  readonly advisorTimeoutMs?: number
+  readonly advisorRefreshTurns?: number
+  readonly advisorScoreThreshold?: number
+  readonly advisorSampleLimit?: number
+  readonly advisorMinTokens?: number
 }
 
 /** Durable global preference exposed through `ctx.settings`. */