dsh-context-compression-improved 0.4.0-beta.1 → 0.5.0

package/packages/selector/lib/pruner.d.ts

@@ -82,6 +82,20 @@ interface PresetOptions {
   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
@@ -158,6 +172,13 @@ 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`. */
 interface ContextCompressionSettings {
@@ -200,6 +221,14 @@ interface ToolResultPruneConfig {
   historyKeepRecentTokens?: number;
   /** Minimum reclaim required before historical aging is worth a cache break. Profile default when omitted. */
   historyMinReclaimTokens?: number;
+  /**
+   * Read-class input cap in characters. Invariant (startup-asserted in
+   * `resolvePolicy`): when set it must exceed `freshTriggerTokens × 4.0` —
+   * the conservative chars/token upper bound — otherwise the cap sits below
+   * the fresh trigger and silently silences the fresh path for every read
+   * result. Unset profiles (host cap 50k–59.5k chars observed) stay untouched.
+   */
+  readInputCapChars?: number;
   /**
    * Auto Compact threshold percent frozen into this deployment by the preset
    * overlay generation (50–90 integer). When present it supersedes the live
@@ -228,6 +257,12 @@ interface CompressionPolicy {
   readonly historyKeepRecentToolCalls: number;
   readonly historyKeepRecentTokens: number;
   readonly historyMinReclaimTokens: number;
+  /**
+   * Read-class input cap in characters when configured; absent otherwise.
+   * Startup-asserted to exceed `freshTriggerTokens × 4.0` so it can never
+   * silently silence the fresh path (G2 invariant).
+   */
+  readonly readInputCapChars?: number;
   /**
    * Auto Compact token watermark `A = floor(C × a)` when the standard-profile
    * History linkage resolved for this Session; absent for Custom, Off, Native,
@@ -266,6 +301,8 @@ interface ResolvedConfig {
   readonly historyKeepRecentToolCalls?: number;
   readonly historyKeepRecentTokens?: number;
   readonly historyMinReclaimTokens?: number;
+  /** Read-class input cap in characters when configured; absent otherwise. */
+  readonly readInputCapChars?: number;
   /**
    * Auto Compact threshold percent frozen into this deployment by the preset
    * overlay generation (50-90 integer). Supersedes the live Host setting.
@@ -320,6 +357,56 @@ interface PruneResult {
   readonly tokensRemoved: number;
 }
 //#endregion
+//#region src/runtime/tokenpilot/sidechannel.d.ts
+/** Audit record of one side-channel call (Phase 13). All fields optional-safe. */
+interface SideChannelAudit {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  /** host|direct plus the resolved provider/model identity. */
+  readonly channel?: string;
+  /** L2 coverage: content shown N of node content total M. */
+  readonly coverage?: {
+    readonly shown: number;
+    readonly total: number;
+  };
+  readonly reason?: string;
+}
+interface SideChannelRequest {
+  readonly system: string;
+  readonly user: string;
+  readonly signal: AbortSignal;
+}
+/** One bound side channel. `ask` resolves `undefined` on ANY failure. */
+declare class SideChannel {
+  private readonly ctx;
+  private readonly options;
+  private readonly overrides?;
+  /**
+   * @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(ctx: Context, options: PresetOptionsSettings, overrides?: {
+    readonly mode?: "" | "host" | "direct";
+    readonly timeoutMs?: number;
+    readonly maxTokens?: number;
+  } | undefined);
+  private get mode();
+  get enabled(): boolean;
+  ask(request: SideChannelRequest): Promise<string | undefined>;
+  /** Failure-open wrapper that also records one audit record per call. */
+  askAudited(request: SideChannelRequest): Promise<{
+    text?: string;
+    audit: SideChannelAudit;
+  }>;
+  identity(): string | undefined;
+  /** Same host-route resolution as the estimator: explicit, then host default. */
+  private resolveHostRoute;
+  private askHost;
+  private askDirect;
+}
+//#endregion
 //#region src/runtime/tokenpilot/estimator.d.ts
 /** Per-session estimator failure bookkeeping for exponential backoff. */
 interface EstimatorFailures {
@@ -516,6 +603,8 @@ interface PrunerState {
   readonly reviewClocks: WeakMap<Session, number>;
   /** Estimator-reported remaining turns Ŝ per Session; advisory only. */
   readonly estimatorRemainingTurns: WeakMap<Session, number>;
+  /** Per-session advisor side channel, constructed once with the advisor overrides. */
+  readonly advisorChannels: WeakMap<Session, SideChannel>;
   /** Four-state outcome counters per Session (floating-window summary row). */
   readonly reviewSummaries: WeakMap<Session, ReviewSessionSummary>;
 }
@@ -622,13 +711,32 @@ interface ReducerOutput {
   readonly text: string;
   readonly reducer: string;
   readonly lossy: boolean;
+  /**
+   * Structured telemetry (task_4c/G7): how many ORIGINAL-event lines the
+   * reducer elided, when the reducer knows it. Never printed into `text` —
+   * host-side logging is what turns this into the compress→retrieve M/N ratio.
+   */
+  readonly elidedLines?: number;
+}
+/**
+ * Optional side-channel ranking (S1a/S1b) handed to the form-dispatched
+ * reducers. Selection and order ONLY — the mechanical fold stays the sole
+ * content authority, and `undefined` reproduces the mechanical output
+ * byte-for-byte. The ranking itself always comes from outside the reducers:
+ * the mechanical layer never calls a model.
+ */
+interface ReductionRanking {
+  /** Search file paths, most relevant first (S1a). Unknown paths are ignored. */
+  readonly files?: readonly string[];
+  /** Document section heading texts, most relevant first (S1b). */
+  readonly sections?: readonly string[];
 }
 /**
  * Select a reducer from verified tool, command, and content evidence.
  * @param input - original result text, recovery source, and output budget.
  * @returns a verified candidate, or `null` when every reducer fails open.
  */
-declare function reduceFreshToolResult(input: ReducerInput): ReducerOutput | null;
+declare function reduceFreshToolResult(input: ReducerInput, ranking?: ReductionRanking): ReducerOutput | null;
 /**
  * Build a recoverable placeholder for an old tool result.
  * @param input - tool identity, source reference, size, status, and retained evidence.
@@ -729,6 +837,11 @@ interface IntrinsicImageBlockDiagnostic {
 interface MeasuredTokenSurfaceNode {
   readonly seq: number;
   readonly count: TokenCount;
+  /**
+   * Authoritative decision metric for this node: character pressure in
+   * Unicode code points (same convention as SnapshotCandidate.characterPressure).
+   */
+  readonly characterPressure: number;
   /** Intrinsic-grid diagnostic when usable image dimensions were available. */
   readonly intrinsicImageBlockEstimate?: IntrinsicImageBlockDiagnostic;
 }
@@ -738,6 +851,11 @@ interface CompactionTokenView extends TokenMeasurement {
   readonly modelId?: string;
   readonly measuredNodes: readonly MeasuredTokenSurfaceNode[];
   readonly currentSurface: TokenCount;
+  /**
+   * Exact character analogue of `currentSurface`: sum of per-node
+   * `characterPressure` over the same nodes `currentSurface` covers.
+   */
+  readonly currentSurfaceChars: number;
   /** Sum of per-node intrinsic padding minima; a diagnostic, not a token bound. */
   readonly intrinsicImageBlockEstimateTokens: number;
   readonly latestEnvelopeKey?: ProviderMeasurementKey;
@@ -802,6 +920,15 @@ declare class ToolResultPruner extends Service {
    * superseded classification.
    */
   private postflightEstimatorPass;
+  /**
+   * Advisory advisor pass at the turn boundary, strictly fire-and-forget.
+   * Produces todolist-bound tail-task summaries, incremental relevance
+   * scores, and a prefix-decay figure — all observational. Every short
+   * circuit below (mode off, re-entry, cooldown, no task semantics, no
+   * direct endpoint) returns without touching any state the pruning chain
+   * reads, so the default configuration adds exactly zero behavior.
+   */
+  private postflightAdvisorPass;
   /**
    * The per-session review queue, or `undefined` while review mode is off
    * (every review path must then behave exactly like before).