@juspay/neurolink 12.18.0 → 12.19.0

package/dist/cli/commands/setup.js

@@ -20,7 +20,7 @@ import { handleGCPSetup } from "./setup-gcp.js";
 import { handleHuggingFaceSetup } from "./setup-huggingface.js";
 import { handleMistralSetup } from "./setup-mistral.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "../../factories/providerDescriptors.js";
-import { createCohereConfig, createDeepSeekConfig, createIdeogramConfig, createJinaConfig, createNvidiaNimConfig, createOpenAICompatibleConfig, createRecraftConfig, createReplicateConfig, createStabilityConfig, createVoyageConfig, satisfiesFallbacks, } from "../../utils/providerConfig.js";
+import { createCohereConfig, createDeepSeekConfig, createIdeogramConfig, createJinaConfig, createNvidiaNimConfig, createOpenAICompatibleConfig, createRecraftConfig, createReplicateConfig, createStabilityConfig, createVoyageConfig, createTypeSafeConfig, satisfiesFallbacks, } from "../../utils/providerConfig.js";
 import { getCatalogJsonEntries, buildCatalogConfigOptions, } from "../../providers/catalog/loader.js";
 // Provider information database
 const PROVIDERS = [
@@ -168,6 +168,7 @@ export const EXTRA_PROVIDER_CONFIGS = {
     stability: createStabilityConfig(),
     ideogram: createIdeogramConfig(),
     recraft: createRecraftConfig(),
+    typesafe: createTypeSafeConfig(),
     ...Object.fromEntries(getCatalogJsonEntries()
         .filter((e) => e.id !== "mistral")
         .map((e) => [e.id, buildCatalogConfigOptions(e)])),

package/dist/cli/factories/commandFactory.d.ts

@@ -486,7 +486,17 @@ export declare class CLICommandFactory {
         classifierStrategy: {
             type: "string";
             description: string;
-            choices: readonly ["heuristic", "llm"];
+            choices: readonly ["auto", "heuristic", "llm", "jev"];
+            alias: string;
+        };
+        classifierMinUpgradeConfidence: {
+            type: "number";
+            description: string;
+            alias: string;
+        };
+        classifierMinDowngradeConfidence: {
+            type: "number";
+            description: string;
             alias: string;
         };
         classifierModelProvider: {
@@ -1379,7 +1389,17 @@ export declare const commonOptions: {
     classifierStrategy: {
         type: "string";
         description: string;
-        choices: readonly ["heuristic", "llm"];
+        choices: readonly ["auto", "heuristic", "llm", "jev"];
+        alias: string;
+    };
+    classifierMinUpgradeConfidence: {
+        type: "number";
+        description: string;
+        alias: string;
+    };
+    classifierMinDowngradeConfidence: {
+        type: "number";
+        description: string;
         alias: string;
     };
     classifierModelProvider: {

package/dist/cli/factories/commandFactory.js

@@ -592,10 +592,20 @@ export class CLICommandFactory {
         },
         classifierStrategy: {
             type: "string",
-            description: "Classifier strategy: 'heuristic' (default, no LLM) or 'llm' (a cheap model picks per prompt).",
-            choices: ["heuristic", "llm"],
+            description: "Classifier strategy: 'auto' (default — 'jev' when TYPESAFE_API_KEY is set, else 'heuristic'), 'heuristic' (no LLM), 'llm' (a cheap model picks per prompt), or 'jev' (TypeSafe System One, ~400ms with calibrated confidence).",
+            choices: ["auto", "heuristic", "llm", "jev"],
             alias: "classifier-strategy",
         },
+        classifierMinUpgradeConfidence: {
+            type: "number",
+            description: "Minimum confidence to route UP to a costlier model; below it the heuristic is used. Only meaningful for 'jev'. Default: 0.3.",
+            alias: "classifier-min-upgrade-confidence",
+        },
+        classifierMinDowngradeConfidence: {
+            type: "number",
+            description: "Minimum confidence to route DOWN to a cheaper model. Higher than the upgrade bar, because the two mistakes cost differently. Default: 0.6.",
+            alias: "classifier-min-downgrade-confidence",
+        },
         classifierModelProvider: {
             type: "string",
             description: "Provider for the LLM classifier model (strategy=llm).",
@@ -959,6 +969,8 @@ export class CLICommandFactory {
             // Classifier-router flags — constructor-level config (see note above).
             classifierRouter: argv.classifierRouter,
             classifierStrategy: argv.classifierStrategy,
+            classifierMinUpgradeConfidence: argv.classifierMinUpgradeConfidence,
+            classifierMinDowngradeConfidence: argv.classifierMinDowngradeConfidence,
             classifierModelProvider: argv.classifierModelProvider,
             classifierModelName: argv.classifierModelName,
             classifierModelRegion: argv.classifierModelRegion,

package/dist/cli/loop/optionsSchema.js

@@ -24,6 +24,10 @@ export const textGenerationOptionsSchema = {
         type: "number",
         description: "The maximum number of tokens to generate.",
     },
+    compactionThreshold: {
+        type: "number",
+        description: "Fraction of the context window (0-1) at which history is compacted. Default 0.8.",
+    },
     topP: {
         type: "number",
         description: "Top-p (nucleus) sampling parameter. Controls diversity of generated tokens (0.0-1.0).",

package/dist/cli/utils/classifierRouterFlags.js

@@ -15,6 +15,13 @@ import { logger } from "../../utils/logger.js";
 // boundary.
 const MAX_POOL_INPUT_BYTES = 1_000_000; // 1 MB
 const MAX_POOL_ENTRIES = 1_000;
+/** Narrow a raw flag string onto the strategy union without an assertion. */
+function isStrategyKind(value) {
+    return (value === "heuristic" ||
+        value === "llm" ||
+        value === "jev" ||
+        value === "auto");
+}
 /**
  * Build a {@link ClassifierRouterConfig} from the parsed CLI flags.
  *
@@ -30,7 +37,12 @@ export function buildClassifierRouterConfigFromCli(flags) {
     if (!flags.classifierRouter) {
         return undefined;
     }
-    const strategy = flags.classifierStrategy === "llm" ? "llm" : "heuristic";
+    // Defaults to "auto", which resolves to "jev" when TYPESAFE_API_KEY is set
+    // and "heuristic" otherwise — so a configured key upgrades CLI routing with
+    // no flag change, and an unset one behaves exactly as before.
+    const strategy = isStrategyKind(flags.classifierStrategy)
+        ? flags.classifierStrategy
+        : "auto";
     const pool = typeof flags.classifierPool === "string" &&
         flags.classifierPool.trim() !== ""
         ? parsePoolFlag(flags.classifierPool)
@@ -52,6 +64,32 @@ export function buildClassifierRouterConfigFromCli(flags) {
             logger.warn(`[classifier-router] --classifier-timeout value ${String(t)} is not a positive finite number; ignoring (SDK default applies).`);
         }
     }
+    // Values above 1 are accepted deliberately: an unreachable floor is a
+    // legitimate way to force the heuristic while leaving the strategy set.
+    const confidenceFlags = [
+        [
+            "classifierMinUpgradeConfidence",
+            "minUpgradeConfidence",
+            "--classifier-min-upgrade-confidence",
+        ],
+        [
+            "classifierMinDowngradeConfidence",
+            "minDowngradeConfidence",
+            "--classifier-min-downgrade-confidence",
+        ],
+    ];
+    for (const [flagKey, configKey, cliName] of confidenceFlags) {
+        const value = flags[flagKey];
+        if (value === undefined) {
+            continue;
+        }
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+            config[configKey] = value;
+        }
+        else {
+            logger.warn(`[classifier-router] ${cliName} value ${String(value)} is not a non-negative finite number; ignoring (SDK default applies).`);
+        }
+    }
     const hasProvider = typeof flags.classifierModelProvider === "string";
     const hasModel = typeof flags.classifierModelName === "string";
     const hasRegion = typeof flags.classifierModelRegion === "string";

package/dist/constants/enums.d.ts

@@ -41,6 +41,8 @@ export declare enum AIProviderName {
     STABILITY = "stability",
     IDEOGRAM = "ideogram",
     RECRAFT = "recraft",
+    /** TypeSafe (Jev) — serves the `decide` inference type only. */
+    TYPESAFE = "typesafe",
     AUTO = "auto"
 }
 /**
@@ -1030,3 +1032,14 @@ export declare enum XaiModels {
     GROK_2_VISION_LATEST = "grok-2-vision-latest",
     GROK_BETA = "grok-beta"
 }
+/**
+ * TypeSafe decision models. Hand-written: TypeSafe is a Tier-3 provider, so
+ * it is not in the provider catalog and codegen never touches this.
+ *
+ * `jev-preview` currently resolves to the same build as `jev-latest`; both
+ * report themselves as a pinned version (e.g. `jev-1.13.0`) in the response.
+ */
+export declare enum TypeSafeModels {
+    JEV_LATEST = "jev-latest",
+    JEV_PREVIEW = "jev-preview"
+}

package/dist/constants/enums.js

@@ -47,6 +47,8 @@ export var AIProviderName;
     AIProviderName["STABILITY"] = "stability";
     AIProviderName["IDEOGRAM"] = "ideogram";
     AIProviderName["RECRAFT"] = "recraft";
+    /** TypeSafe (Jev) — serves the `decide` inference type only. */
+    AIProviderName["TYPESAFE"] = "typesafe";
     AIProviderName["AUTO"] = "auto";
 })(AIProviderName || (AIProviderName = {}));
 /**
@@ -1301,3 +1303,15 @@ export var XaiModels;
     XaiModels["GROK_BETA"] = "grok-beta";
 })(XaiModels || (XaiModels = {}));
 // ── END GENERATED(models-enums) ──
+/**
+ * TypeSafe decision models. Hand-written: TypeSafe is a Tier-3 provider, so
+ * it is not in the provider catalog and codegen never touches this.
+ *
+ * `jev-preview` currently resolves to the same build as `jev-latest`; both
+ * report themselves as a pinned version (e.g. `jev-1.13.0`) in the response.
+ */
+export var TypeSafeModels;
+(function (TypeSafeModels) {
+    TypeSafeModels["JEV_LATEST"] = "jev-latest";
+    TypeSafeModels["JEV_PREVIEW"] = "jev-preview";
+})(TypeSafeModels || (TypeSafeModels = {}));

package/dist/context/budgetChecker.d.ts

@@ -7,6 +7,8 @@
  * This runs BEFORE every LLM call to prevent context overflow.
  */
 import type { BudgetCheckResult, BudgetCheckParams } from "../types/index.js";
+/** Default compaction threshold (80% of available input) */
+export declare const DEFAULT_COMPACTION_THRESHOLD = 0.8;
 /**
  * Tokens the CONVERSATION HISTORY may occupy, i.e. the model's available input
  * space minus everything that rides alongside it (system prompt, current
@@ -22,7 +24,7 @@ import type { BudgetCheckResult, BudgetCheckParams } from "../types/index.js";
  * Returns 0 when the fixed overhead already exceeds the window; callers must
  * treat that as unrecoverable rather than compacting to an empty history.
  */
-export declare function resolveHistoryBudget(result: BudgetCheckResult): number;
+export declare function resolveHistoryBudget(result: BudgetCheckResult, compactionThreshold?: number): number;
 /**
  * Check whether a request fits within the model's context budget.
  *

package/dist/context/budgetChecker.js

@@ -11,7 +11,7 @@ import { estimateMessagesTokens, estimateTokens, TOKENS_PER_MESSAGE, } from "../
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /** Default compaction threshold (80% of available input) */
-const DEFAULT_COMPACTION_THRESHOLD = 0.8;
+export const DEFAULT_COMPACTION_THRESHOLD = 0.8;
 /**
  * Fraction of the derived history budget actually handed to the compactor.
  * Estimation is char-based and approximate, so the compactor aims slightly
@@ -35,16 +35,27 @@ const TOKENS_PER_TOOL_DEFINITION = 200;
  * Returns 0 when the fixed overhead already exceeds the window; callers must
  * treat that as unrecoverable rather than compacting to an empty history.
  */
-export function resolveHistoryBudget(result) {
+export function resolveHistoryBudget(result, compactionThreshold) {
     const { availableInputTokens, breakdown } = result;
+    // A per-request threshold says how much of the window this request should
+    // occupy. Expressed against the 0.8 default it becomes a pure scale factor,
+    // so the default reproduces the previous number EXACTLY (0.8/0.8 = 1) and
+    // anything lower shrinks the target. Clamped to at most 1 because this is
+    // the "give the model less context" lever, never the "give it more" one —
+    // over-filling a window is a hard provider error that ModelPool records as
+    // a permanent cooldown.
+    const scale = compactionThreshold === undefined
+        ? 1
+        : Math.max(0, Math.min(1, compactionThreshold / DEFAULT_COMPACTION_THRESHOLD));
+    const factor = HISTORY_BUDGET_SAFETY_FACTOR * scale;
     if (!breakdown) {
-        return Math.max(0, Math.floor(availableInputTokens * HISTORY_BUDGET_SAFETY_FACTOR));
+        return Math.max(0, Math.floor(availableInputTokens * factor));
     }
     const overhead = breakdown.systemPrompt +
         breakdown.currentPrompt +
         breakdown.toolDefinitions +
         breakdown.fileAttachments;
-    return Math.max(0, Math.floor((availableInputTokens - overhead) * HISTORY_BUDGET_SAFETY_FACTOR));
+    return Math.max(0, Math.floor((availableInputTokens - overhead) * factor));
 }
 /**
  * Check whether a request fits within the model's context budget.
@@ -116,6 +127,11 @@ export function checkContextBudget(params) {
             "context.triggered": shouldCompact,
             "context.estimatedTokens": estimatedInputTokens,
             "context.availableTokens": availableInputTokens,
+            // The threshold this check actually used. `shouldCompact` is
+            // meaningless without it once the threshold became per-request:
+            // the same usageRatio can be over budget for one request and under
+            // it for the next.
+            "context.compactionThreshold": compactionThreshold,
         }), SpanStatus.OK);
         getMetricsAggregator().recordSpan(endedSpan);
         return result;

package/dist/context/contextCompactor.d.ts

@@ -8,12 +8,52 @@
  * Stage 3: LLM Summarization (expensive -- requires LLM call)
  * Stage 4: Sliding Window Truncation (fallback -- no LLM call)
  */
-import type { ChatMessage, ConversationMemoryConfig, CompactionResult, CompactionConfig } from "../types/index.js";
+import type { ChatMessage, ConversationMemoryConfig, CompactionResult, CompactionConfig, ContextCompactorDeps, ContextCompactRequest } from "../types/index.js";
 export declare class ContextCompactor {
     private config;
-    constructor(config?: CompactionConfig);
+    /**
+     * Injected decision caller and its tuning. Kept OUT of `CompactionConfig`
+     * deliberately: that type is `Required<>`-ed into `DEFAULT_CONFIG`, so a
+     * function member would need a default implementation, and the compactor
+     * must stay usable with no decision provider at all.
+     */
+    private readonly deps;
+    constructor(config?: CompactionConfig, deps?: ContextCompactorDeps);
     /**
      * Run the multi-stage compaction pipeline until messages fit within budget.
      */
-    compact(messages: ChatMessage[], targetTokens: number, memoryConfig?: Partial<ConversationMemoryConfig>, requestId?: string): Promise<CompactionResult>;
+    compact(messages: ChatMessage[], targetTokens: number, memoryConfig?: Partial<ConversationMemoryConfig>, requestId?: string, request?: ContextCompactRequest): Promise<CompactionResult>;
+    /**
+     * Stage 0 — drop the earlier messages this request provably does not need.
+     *
+     * Returns the surviving messages, or `null` when nothing changed: no
+     * decision provider, no known request, nothing eligible, or no confident
+     * drop. Never throws — a failure here must leave the positional stages to
+     * run exactly as they did before this stage existed.
+     */
+    private runRelevanceStage;
+    /**
+     * Whether a generated summary may replace the messages it covers.
+     *
+     * Stage 3 accepts any non-empty string today, so a refusal, an error
+     * message or a truncated fragment silently destroys the conversation it was
+     * meant to preserve — and the originals are gone before anyone reads it.
+     *
+     * Returns true unless a decision model CONFIDENTLY rejects the summary,
+     * because rejecting one falls through to truncation, which loses strictly
+     * more than an imperfect summary does.
+     */
+    private acceptSummary;
+    /**
+     * Stage 2 — collapse repeated reads of the same file to the last one.
+     * Returns the deduplicated messages, or `null` when the stage is disabled,
+     * already within budget, or found nothing to collapse.
+     */
+    private runDeduplicateStage;
+    /**
+     * Stage 1 — shrink large tool outputs outside the protected recent window.
+     * Returns the pruned messages, or `null` when the stage is disabled,
+     * already within budget, or saved nothing worth keeping.
+     */
+    private runPruneStage;
 }

package/dist/context/contextCompactor.js

@@ -19,6 +19,7 @@ import { pruneToolOutputs } from "./stages/toolOutputPruner.js";
 import { deduplicateFileReads } from "./stages/fileReadDeduplicator.js";
 import { truncateWithSlidingWindow } from "./stages/slidingWindowTruncator.js";
 import { summarizeMessages } from "./stages/structuredSummarizer.js";
+import { selectIrrelevantMessages, summaryPreservesContext, } from "./contextDecision.js";
 const DEFAULT_CONFIG = {
     enablePrune: true,
     enableDeduplicate: true,
@@ -35,13 +36,21 @@ const DEFAULT_CONFIG = {
 };
 export class ContextCompactor {
     config;
-    constructor(config) {
+    /**
+     * Injected decision caller and its tuning. Kept OUT of `CompactionConfig`
+     * deliberately: that type is `Required<>`-ed into `DEFAULT_CONFIG`, so a
+     * function member would need a default implementation, and the compactor
+     * must stay usable with no decision provider at all.
+     */
+    deps;
+    constructor(config, deps) {
         this.config = { ...DEFAULT_CONFIG, ...config };
+        this.deps = deps ?? {};
     }
     /**
      * Run the multi-stage compaction pipeline until messages fit within budget.
      */
-    async compact(messages, targetTokens, memoryConfig, requestId) {
+    async compact(messages, targetTokens, memoryConfig, requestId, request) {
         return withSpan({
             name: "neurolink.context.compact",
             tracer: tracers.context,
@@ -66,46 +75,27 @@ export class ContextCompactor {
                     estimatedTokens: tokensBefore,
                     budgetTokens: targetTokens,
                 });
+                // Stage 0: Relevance. Runs FIRST, and only when a decision
+                // provider is configured and the current request is known — every
+                // later stage is positional, so removing what the request provably
+                // does not need before they run means they have less to throw away
+                // by recency alone. Fails open to exactly the previous pipeline.
+                const afterRelevance = await this.runRelevanceStage(currentMessages, provider, targetTokens, request, requestId);
+                if (afterRelevance) {
+                    currentMessages = afterRelevance;
+                    stagesUsed.push("relevance");
+                }
                 // Stage 1: Tool Output Pruning
-                if (this.config.enablePrune &&
-                    estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-                    const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-                    const pruneResult = pruneToolOutputs(currentMessages, {
-                        protectTokens: this.config.pruneProtectTokens,
-                        minimumSavings: this.config.pruneMinimumSavings,
-                        protectedTools: this.config.pruneProtectedTools,
-                        provider,
-                    });
-                    if (pruneResult.pruned) {
-                        currentMessages = pruneResult.messages;
-                        stagesUsed.push("prune");
-                    }
-                    const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                    logger.info("[Compaction] Stage 1 (prune)", {
-                        requestId,
-                        ran: pruneResult.pruned,
-                        tokensBefore: stageTokensBefore,
-                        tokensAfter: stageTokensAfter,
-                        saved: stageTokensBefore - stageTokensAfter,
-                    });
+                const afterPrune = this.runPruneStage(currentMessages, provider, targetTokens, requestId);
+                if (afterPrune) {
+                    currentMessages = afterPrune;
+                    stagesUsed.push("prune");
                 }
                 // Stage 2: File Read Deduplication
-                if (this.config.enableDeduplicate &&
-                    estimateMessagesTokens(currentMessages, provider) > targetTokens) {
-                    const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
-                    const dedupResult = deduplicateFileReads(currentMessages);
-                    if (dedupResult.deduplicated) {
-                        currentMessages = dedupResult.messages;
-                        stagesUsed.push("deduplicate");
-                    }
-                    const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
-                    logger.info("[Compaction] Stage 2 (deduplicate)", {
-                        requestId,
-                        ran: dedupResult.deduplicated,
-                        tokensBefore: stageTokensBefore,
-                        tokensAfter: stageTokensAfter,
-                        saved: stageTokensBefore - stageTokensAfter,
-                    });
+                const afterDedup = this.runDeduplicateStage(currentMessages, provider, targetTokens, requestId);
+                if (afterDedup) {
+                    currentMessages = afterDedup;
+                    stagesUsed.push("deduplicate");
                 }
                 // Stage 3: LLM Summarization
                 if (this.config.enableSummarize &&
@@ -119,7 +109,16 @@ export class ContextCompactor {
                             memoryConfig,
                             targetTokens,
                         }), 120_000, "LLM summarization timed out after 120s");
-                        if (summarizeResult.summarized) {
+                        // Gate the summary before it replaces anything — see
+                        // acceptSummary for why a rejection is deliberately rare.
+                        const summaryAccepted = summarizeResult.summarized &&
+                            (await this.acceptSummary(currentMessages, summarizeResult.messages));
+                        if (summarizeResult.summarized && !summaryAccepted) {
+                            span = SpanSerializer.updateAttributes(span, {
+                                "compaction.stage3.summaryRejected": true,
+                            });
+                        }
+                        if (summaryAccepted) {
                             // Pinned skill instructions must survive summarization:
                             // re-seat any that the summarized region swallowed right
                             // after the summary message (index 0 of the result).
@@ -140,7 +139,7 @@ export class ContextCompactor {
                         const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
                         logger.info("[Compaction] Stage 3 (summarize)", {
                             requestId,
-                            ran: summarizeResult.summarized,
+                            ran: summaryAccepted,
                             tokensBefore: stageTokensBefore,
                             tokensAfter: stageTokensAfter,
                             saved: stageTokensBefore - stageTokensAfter,
@@ -254,4 +253,121 @@ export class ContextCompactor {
             }
         }); // end withSpan
     }
+    /**
+     * Stage 0 — drop the earlier messages this request provably does not need.
+     *
+     * Returns the surviving messages, or `null` when nothing changed: no
+     * decision provider, no known request, nothing eligible, or no confident
+     * drop. Never throws — a failure here must leave the positional stages to
+     * run exactly as they did before this stage existed.
+     */
+    async runRelevanceStage(messages, provider, targetTokens, request, requestId) {
+        if (!this.deps.decide || !request?.currentRequest) {
+            return null;
+        }
+        const tokensBefore = estimateMessagesTokens(messages, provider);
+        if (tokensBefore <= targetTokens) {
+            return null;
+        }
+        try {
+            const relevance = await selectIrrelevantMessages(messages, request.currentRequest, this.deps.decide, this.deps.relevance);
+            logger.info("[Compaction] Stage 0 (relevance)", {
+                requestId,
+                ran: !!relevance,
+                tokensBefore,
+                tokensAfter: relevance
+                    ? estimateMessagesTokens(relevance.messages, provider)
+                    : tokensBefore,
+                droppedCount: relevance?.droppedIndices.length ?? 0,
+            });
+            return relevance ? relevance.messages : null;
+        }
+        catch (error) {
+            logger.warn("[Compaction] Stage 0 (relevance) FAILED", {
+                requestId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Whether a generated summary may replace the messages it covers.
+     *
+     * Stage 3 accepts any non-empty string today, so a refusal, an error
+     * message or a truncated fragment silently destroys the conversation it was
+     * meant to preserve — and the originals are gone before anyone reads it.
+     *
+     * Returns true unless a decision model CONFIDENTLY rejects the summary,
+     * because rejecting one falls through to truncation, which loses strictly
+     * more than an imperfect summary does.
+     */
+    async acceptSummary(before, after) {
+        if (!this.deps.decide) {
+            return true;
+        }
+        const survivingIds = new Set(after.map((m) => m.id));
+        const replaced = before.filter((m) => !survivingIds.has(m.id));
+        const summaryText = after.find((m) => m.metadata?.isSummary)?.content;
+        if (!summaryText || replaced.length === 0) {
+            return true;
+        }
+        return summaryPreservesContext(summaryText, replaced, this.deps.decide, this.deps.summaryGate);
+    }
+    /**
+     * Stage 2 — collapse repeated reads of the same file to the last one.
+     * Returns the deduplicated messages, or `null` when the stage is disabled,
+     * already within budget, or found nothing to collapse.
+     */
+    runDeduplicateStage(messages, provider, targetTokens, requestId) {
+        if (!this.config.enableDeduplicate) {
+            return null;
+        }
+        const tokensBefore = estimateMessagesTokens(messages, provider);
+        if (tokensBefore <= targetTokens) {
+            return null;
+        }
+        const dedupResult = deduplicateFileReads(messages);
+        const tokensAfter = dedupResult.deduplicated
+            ? estimateMessagesTokens(dedupResult.messages, provider)
+            : tokensBefore;
+        logger.info("[Compaction] Stage 2 (deduplicate)", {
+            requestId,
+            ran: dedupResult.deduplicated,
+            tokensBefore,
+            tokensAfter,
+            saved: tokensBefore - tokensAfter,
+        });
+        return dedupResult.deduplicated ? dedupResult.messages : null;
+    }
+    /**
+     * Stage 1 — shrink large tool outputs outside the protected recent window.
+     * Returns the pruned messages, or `null` when the stage is disabled,
+     * already within budget, or saved nothing worth keeping.
+     */
+    runPruneStage(messages, provider, targetTokens, requestId) {
+        if (!this.config.enablePrune) {
+            return null;
+        }
+        const tokensBefore = estimateMessagesTokens(messages, provider);
+        if (tokensBefore <= targetTokens) {
+            return null;
+        }
+        const pruneResult = pruneToolOutputs(messages, {
+            protectTokens: this.config.pruneProtectTokens,
+            minimumSavings: this.config.pruneMinimumSavings,
+            protectedTools: this.config.pruneProtectedTools,
+            provider,
+        });
+        const tokensAfter = pruneResult.pruned
+            ? estimateMessagesTokens(pruneResult.messages, provider)
+            : tokensBefore;
+        logger.info("[Compaction] Stage 1 (prune)", {
+            requestId,
+            ran: pruneResult.pruned,
+            tokensBefore,
+            tokensAfter,
+            saved: tokensBefore - tokensAfter,
+        });
+        return pruneResult.pruned ? pruneResult.messages : null;
+    }
 }

package/dist/context/contextDecision.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Relevance-driven context compaction.
+ *
+ * Every stage of the existing compactor is *positional*: prune protects the
+ * most recent 40K tokens, truncation drops the oldest half, summarization
+ * keeps a trailing ratio. None of them has any notion of what the current
+ * request is about, so a fifty-turn conversation that ends with "now rename
+ * that variable" keeps the forty turns about database migrations and drops
+ * nothing that matters less.
+ *
+ * A decision model changes the economics of asking. Latency is flat in
+ * question count — one question and four hundred questions cost the same
+ * round trip — so "is this message needed to answer the current request?" can
+ * be asked about *every* message at once, for about $0.00002.
+ *
+ * What it must never do is lose something the turn needed. The guards below
+ * are therefore deliberately conservative, and every one of them is a veto:
+ *
+ * - only plain user/assistant text is ever eligible; tool calls, tool
+ *   results, summaries, pinned skills and system messages are untouchable,
+ *   because dropping half of a tool-call pair produces a malformed request
+ *   rather than a smaller one
+ * - the most recent messages are never eligible, whatever the model says
+ * - a message is dropped only on a CONFIDENT no, never on silence or a
+ *   near-coin-flip
+ * - at most a bounded fraction of eligible messages may go in one pass
+ *
+ * @module context/contextDecision
+ */
+import type { ChatMessage, ContextRelevanceOptions, ContextRelevanceResult, DecisionCallerFn } from "../types/index.js";
+/**
+ * Ask which earlier messages the current request still needs, and return the
+ * ones to drop.
+ *
+ * Returns `null` when nothing should change — no decision provider, a failed
+ * call, nothing eligible, or no confident drop. A null return is the signal
+ * to carry on with positional compaction exactly as before.
+ */
+export declare function selectIrrelevantMessages(messages: ChatMessage[], currentRequest: string, decide: DecisionCallerFn, options?: ContextRelevanceOptions): Promise<ContextRelevanceResult | null>;
+/**
+ * Gate a generated summary before it replaces the messages it covers.
+ *
+ * Stage 3 accepts any non-empty string today, so a summarizer that returned
+ * an apology, a refusal, or a truncated fragment silently destroys the
+ * conversation it was meant to preserve — and the messages are gone by the
+ * time anyone reads the summary.
+ *
+ * Returns `true` when the summary may be used and `false` only on a confident
+ * rejection. Anything else — no decision provider, a failed call, an
+ * unanswered or uncertain verdict — returns `true`, because refusing a
+ * summary means falling through to truncation, which loses strictly more.
+ */
+export declare function summaryPreservesContext(summary: string, replacedMessages: ChatMessage[], decide: DecisionCallerFn, options?: {
+    timeoutMs?: number;
+    minConfidence?: number;
+}): Promise<boolean>;