@falling-ts/dsh-force-compact 0.2.0

package/src/core/pairing.js

@@ -0,0 +1,188 @@
+/**
+ * Tool-pairing balance over a session surface — ported verbatim (plain JS, no
+ * type layer) from the official `@deepseek-ai/dsh-compaction` tool-pairing
+ * ledger (`deepseek-harness/packages/compaction/compaction/src/tool-pairing.ts`).
+ *
+ * Compaction changes surface positions, so safe cuts are derived from
+ * tool-call/result content in current surface order rather than step markers.
+ *
+ * Balance definition (official semantics):
+ *   • an `assistant/message` event contributes +N where N is the number of
+ *     `tool-call` content blocks in `data.message.content`;
+ *   • a `tool/result` event contributes -1;
+ *   • every other event contributes 0.
+ * A surface CUT (between two consecutive surface positions, or before the
+ * first / after the last) is BALANCED when the running in-progress tool-call
+ * count at that cut is 0 — i.e. no unanswered tool call straddles the cut.
+ * A surface of N nodes therefore has N+1 cuts; the leading cut (before the
+ * first node) is trivially balanced.
+ *
+ * The balance table is computed incrementally and cached PER SESSION behind a
+ * `WeakMap` keyed on the session object (mirrors the official
+ * `balanceCacheBySession`). The cache advances only over the NEW suffix of the
+ * surface (appends), so repeated reads over a growing surface stay near-O(new
+ * nodes). A surface REPLACEMENT (compactation checkpoint landing) bumps the
+ * session's `replaceGeneration`, which forces a full rebuild from scratch —
+ * exactly the official rebuild path ("the same fold started from the
+ * empty-surface state").
+ *
+ * Corrupt-surface handling matches the official module: a surface sequence
+ * whose log slot holds a different event (`eventForSeq` mismatch) or a
+ * `tool/result` with no preceding open call THROWS, so a corrupted log can
+ * never leave a partially-advanced cache state behind (the tail is validated
+ * BEFORE the live cache mutates). Callers in this plugin wrap the public
+ * predicates in safe envelopes that degrade to "assume balanced" rather than
+ * throwing into the compaction path — see `safe*` variants below.
+ *
+ * @module @falling-ts/dsh-force-compact/pairing
+ */
+
+/**
+ * Incremental balance state for one session surface generation.
+ * @typedef {Object} BalanceCache
+ * @property {number} generation Surface rewrite generation this state
+ *   describes (`session.surface.replaceGeneration`).
+ * @property {ReadonlyArray<boolean>} cutBalanced Balance of every surface cut
+ *   in current order: a surface of N sequences has N + 1 cuts, entry `i`
+ *   being the cut before sequence `i` and the final entry the cut after the
+ *   surface tail.
+ * @property {Map<number, number>} indexBySeq Current surface position of each
+ *   event seq, indexing {@link BalanceCache#cutBalanced}.
+ * @property {number} inProgressToolCalls In-progress tool-call count after
+ *   the processed surface tail.
+ */
+
+const balanceCacheBySession = new WeakMap()
+
+/** How one surface event changes the in-progress tool-call count (official `eventDelta`). */
+export function eventDelta(event) {
+  const type = event && event.type
+  if (type === 'assistant/message') {
+    const message = event.data && event.data.message
+    const content = (message && Array.isArray(message.content)) ? message.content : []
+    return content.filter(block => block && block.type === 'tool-call').length
+  }
+  if (type === 'tool/result') return -1
+  return 0
+}
+
+/** Read and validate the event named by a surface sequence (official `eventForSeq`). */
+function eventForSeq(events, seq) {
+  const event = events[seq]
+  if (event === undefined || event.seq !== seq) {
+    throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`)
+  }
+  return event
+}
+
+/** Fold surface sequences not yet in the cache into its balance state (official `extendCache`). */
+function extendCache(session, cache, seqs) {
+  const processed = cache.cutBalanced.length - 1
+  const tail = seqs.slice(processed)
+  // Validate the unseen tail BEFORE mutating the live cache, so a corrupt
+  // append cannot leave a partially advanced state behind.
+  const events = session.events
+  const pendingCuts = []
+  let inProgressToolCalls = cache.inProgressToolCalls
+  for (const seq of tail) {
+    inProgressToolCalls += eventDelta(eventForSeq(events, seq))
+    if (inProgressToolCalls < 0) {
+      throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`)
+    }
+    pendingCuts.push(inProgressToolCalls === 0)
+  }
+
+  tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset))
+  cache.cutBalanced = cache.cutBalanced.concat(pendingCuts)
+  cache.inProgressToolCalls = inProgressToolCalls
+  return cache
+}
+
+/** Balance state synchronized with the current session surface (official `balanceCache`). */
+function balanceCache(session) {
+  const surface = session.surface
+  const seqs = surface.nodes
+  const generation = (surface.replaceGeneration === undefined) ? 0 : surface.replaceGeneration
+  const cached = balanceCacheBySession.get(session)
+
+  if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) {
+    // A rebuild is the same fold started from the empty-surface state, whose
+    // single leading cut is trivially balanced.
+    const rebuilt = extendCache(session, {
+      generation,
+      cutBalanced: [true],
+      indexBySeq: new Map(),
+      inProgressToolCalls: 0,
+    }, seqs)
+    balanceCacheBySession.set(session, rebuilt)
+    return rebuilt
+  }
+  if (cached.cutBalanced.length - 1 < seqs.length) return extendCache(session, cached, seqs)
+  return cached
+}
+
+/** Balance of the cut at a sequence's position plus offset; rejects foreign seqs (official `cutBalance`). */
+function cutBalance(cache, seq, offset) {
+  const index = cache.indexBySeq.get(seq)
+  const balanced = index === undefined ? undefined : cache.cutBalanced[index + offset]
+  if (balanced === undefined) {
+    throw new Error(`tool-pairing balance: surface seq ${seq} not found`)
+  }
+  return balanced
+}
+
+/**
+ * Whether the cut immediately BEFORE a current surface sequence is tool-pairing
+ * balanced (official `toolPairingBalancedBefore`). THROWS on a corrupt surface
+ * or a seq absent from the current surface — use {@link toolPairingBalancedBeforeSafe}
+ * on plugin hot paths.
+ * @param {import('@deepseek-ai/dsh-session').Session} session
+ * @param {number} seq
+ * @returns {boolean}
+ */
+export function toolPairingBalancedBefore(session, seq) {
+  return cutBalance(balanceCache(session), seq, 0)
+}
+
+/**
+ * Whether the cut immediately AFTER a current surface sequence is tool-pairing
+ * balanced (official `toolPairingBalancedAfter`). THROWING variant — see the
+ * `Before` twin.
+ * @param {import('@deepseek-ai/dsh-session').Session} session
+ * @param {number} seq
+ * @returns {boolean}
+ */
+export function toolPairingBalancedAfter(session, seq) {
+  return cutBalance(balanceCache(session), seq, 1)
+}
+
+/**
+ * Safe variant for plugin hot paths: identical math, but a corrupt-surface
+ * throw DETERMINES "this cut is balanced" (returns `true`) so a damaged log
+ * degrades to "attempt the compaction" (where the session core's own replace
+ * validation is the last line of defense) instead of wedging the whole
+ * compaction path in a perpetual selection-failure loop.
+ * @param {import('@deepseek-ai/dsh-session').Session} session
+ * @param {number} seq
+ * @returns {boolean}
+ */
+export function toolPairingBalancedBeforeSafe(session, seq) {
+  try {
+    return toolPairingBalancedBefore(session, seq)
+  } catch (error) {
+    const message = (error instanceof Error) ? error.message : String(error)
+    try { console.warn(`[force-compact] pairing-ledger degraded (assuming balanced before seq ${seq}): ${message}`) } catch { /* never throw out */ }
+    return true
+  }
+}
+
+/** Safe trailing-cut twin of {@link toolPairingBalancedBeforeSafe}. */
+export function toolPairingBalancedAfterSafe(session, seq) {
+  try {
+    return toolPairingBalancedAfter(session, seq)
+  } catch (error) {
+    const message = (error instanceof Error) ? error.message : String(error)
+    try { console.warn(`[force-compact] pairing-ledger degraded (assuming balanced after seq ${seq}): ${message}`) } catch { /* never throw out */ }
+    return true
+  }
+}

package/src/core/policy.js

@@ -0,0 +1,35 @@
+/**
+ * dsh-force-compact tunables.
+ *
+ * These are the plugin's own compaction policy knobs. They are deliberately
+ * fixed constants (not cordis `Config` fields): a standalone Host listener has
+ * no `Config` schema, and a deployment that wants a different policy points its
+ * composition at the `compaction` service's own `retainRatio` / `summarizationModel`
+ * instead — see AGENTS.md for why.
+ * @module @falling-ts/dsh-force-compact/config
+ */
+
+/** Minimum surface nodes before any compaction is considered. */
+export const MIN_NODES = 6
+
+/** Fraction of the recent tail (by surface-node count) retained verbatim and never compacted. */
+export const RETAIN_RATIO = 0.25
+
+/** Compact only when the compactable prefix (all but the retained tail) spans at least this many surface nodes. */
+export const MIN_COMPACTABLE_NODES = 4
+
+/** Generation cap for the summarization call. */
+export const MAX_SUMMARY_TOKENS = 16384
+
+/**
+ * Resolve the full config object for a compaction round.
+ * @returns {Readonly<{minNodes: number, retainRatio: number, minCompactableNodes: number, maxSummaryTokens: number}>}
+ */
+export function resolveConfig() {
+  return Object.freeze({
+    minNodes: MIN_NODES,
+    retainRatio: RETAIN_RATIO,
+    minCompactableNodes: MIN_COMPACTABLE_NODES,
+    maxSummaryTokens: MAX_SUMMARY_TOKENS,
+  })
+}

package/src/core/projected.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-force-compact shared reader for the official `projectedTokens` reading.
+ *
+ * WHY THIS MODULE
+ * ---------------
+ * Every threshold gate, region-selection budget basis, and diagnostic line in
+ * the plugin must key off the SAME number the harness renders in the bottom-right
+ * corner (`上下文已用 xx% / ~xxK / xxK`). That rendered figure IS the
+ * `projectedTokens` member of the host `contextPressure` projection — the
+ * provider-anchored sample plus the surface movement since the sample. Reading
+ * it through the official registry keeps a single definition of the pressure
+ * basis alive inside the plugin instead of a parallel heuristic drifting from
+ * upstream revisions.
+ *
+ * WHERE IT COMES FROM
+ * --------------------
+ * `ctx.get('sessionProjections')` is the host registry that DRIVES every
+ * registered projection unit forward eagerly over committed session events
+ * (framework-owned watermark cache). `snapshot(session).values.contextPressure`
+ * hands back the SAME wire object the host broadcasts to the browser as
+ * `session/projection` frames — already validated against the unit's own
+ * `viewSchema`, so the plugin never re-implements the anchor math. Fields are
+ * individually optional (`pressureTokens` / `projectedTokens` /
+ * `contextWindow`): absent until a provider reports usage.
+ *
+ * SEMANTICS (mirrors the official JSDoc — read before building gates on this)
+ * ----------------------------------------------------------------------------
+ * The three members are INDEPENDENT last-wins records, not one atomic request
+ * observation: switching models can pair a fresh capacity with the previous
+ * route's pressure until the next request reports usage. Official stance —
+ * this is a USER-FACING REFERENCE, not a billing or gating input. The plugin
+ * therefore treats `projectedTokens` as the authoritative pressure basis but
+ * FAILS OPEN (returns `undefined`) when it is absent, so a session that has
+ * not reported usage yet still degrades gracefully to the char-based
+ * estimator at each call site instead of blocking.
+ *
+ * CALIBER NOTES FOR CALLERS
+ * -------------------------
+ * `projectedTokens` = `max(0, pressureTokens + surfaceTokens −
+ * sampledSurfaceTokens)`. The delta term is estimated at the meter's fixed
+ * density (CHARS_PER_TOKEN=4), so the figure UNDERCOUNTS heavy-CJK / tool-JSON
+ * content relative to the pure `surfaceTokens` sum — a deliberate provider
+ * anchor the meter prefers over the unanchored sum. Gate thresholds calibrated
+ * against the old `surfaceTokens` basis sit slightly higher (fewer triggers)
+ * after this swap; that is intended behaviour, not a bug.
+ *
+ * COST CONTRACT
+ * -------------
+ * Sync, pure read. First touch of a freshly-restarted long session replays the
+ * whole log once (lazy fold seeding) — O(events); every later call in the same
+ * process hits the eager-fold watermark cache — effectively O(1). Call sites
+ * are the pre-step gate (once per model step) and the retained-tail path (rare
+ * compaction rounds), so the hot-path cost is negligible.
+ *
+ * FAILURE MODES — ALL RESOLVED TO `undefined` (never throw)
+ * ---------------------------------------------------------
+ * • `ctx` / `ctx.get` absent or not a function → `undefined`
+ * • `sessionProjections` registry not mounted (trimmed compositions) → `undefined`
+ * • `snapshot` throws on a transient backend fault → caught, `undefined`
+ * • `session` unusable → `undefined`
+ * • `contextPressure` unit not folded for this session → `undefined`
+ * • unit present but `projectedTokens` still absent (no usage sample yet) → `undefined`
+ *
+ * Callers pair a `=== undefined` result with their existing char-estimator
+ * fallback (see `estimateSessionTokens` / `estimateSurfaceTokensLocal`), so a
+ * degraded registry never blocks a model request or a compaction commit.
+ *
+ * @module @falling-ts/dsh-force-compact/projected
+ */
+
+/**
+ * Read the official `projectedTokens` for one session — the SAME number the
+ * harness renders in the bottom-right corner.
+ *
+ * Fail-open by design (see module doc): every absence/degradation resolves to
+ * `undefined` rather than propagating. Pair the result with a char-based
+ * estimator fallback at each call site.
+ *
+ * @param {object} ctx cordis context (Host listener `this` / apply ctx).
+ * @param {object|undefined} session live session handle.
+ * @returns {number|undefined} the official `projectedTokens` reading, or
+ *   `undefined` when the registry is unavailable, the snapshot failed, the
+ *   unit is not folded for this session, or no usage sample has been captured
+ *   yet (all fail-open — caller decides the fallback).
+ */
+export function getProjectedTokens(ctx, session) {
+  try {
+    if (typeof ctx?.get !== 'function') return undefined
+    const registry = ctx.get('sessionProjections')
+    if (registry === undefined || registry === null) return undefined
+    if (typeof registry.snapshot !== 'function') return undefined
+    if (session === undefined || session === null) return undefined
+    const snap = registry.snapshot(session)
+    const cp = snap && snap.values && snap.values.contextPressure
+    if (cp === undefined || cp === null) return undefined
+    const projected = cp.projectedTokens
+    return (typeof projected === 'number' && Number.isFinite(projected)) ? projected : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Classify WHY {@link getProjectedTokens} resolved to `undefined` for one
+ * session — a DIAGNOSTIC aid that reproduces the same read but labels the exact
+ * failure tier, so an operator can tell apart "registry/service not reachable
+ * from this context" from "reachable but the session simply has no usage sample
+ * yet". Pure, sync, never throws, returns a short stable reason string (or
+ * `'available'` with the numeric reading attached when the read succeeds).
+ *
+ * @param {object} ctx cordis context.
+ * @param {object|undefined} session live session handle.
+ * @returns {string} one of: `available:<n>` / `no-ctx.get` / `registry-absent` /
+ *   `registry-no-snapshot` / `session-unusable` / `snap-threw` /
+ *   `unit-not-folded` / `no-usage-sample-yet`.
+ */
+export function diagnoseProjectedTokensAbsence(ctx, session) {
+  try {
+    if (typeof ctx?.get !== 'function') return 'no-ctx.get'
+    const registry = ctx.get('sessionProjections')
+    if (registry === undefined || registry === null) return 'registry-absent'
+    if (typeof registry.snapshot !== 'function') return 'registry-no-snapshot'
+    if (session === undefined || session === null) return 'session-unusable'
+    let snap
+    try {
+      snap = registry.snapshot(session)
+    } catch {
+      return 'snap-threw'
+    }
+    const cp = snap && snap.values && snap.values.contextPressure
+    if (cp === undefined || cp === null) return 'unit-not-folded'
+    const projected = cp.projectedTokens
+    return (typeof projected === 'number' && Number.isFinite(projected))
+      ? `available:${projected}`
+      : 'no-usage-sample-yet'
+  } catch {
+    return 'unexpected-throw'
+  }
+}