@cuylabs/agent-core 4.8.1 → 4.10.0

package/dist/context/index.js

@@ -0,0 +1,90 @@
+import {
+  assembleModelContext
+} from "../chunk-IQA64CAO.js";
+import {
+  ContextSummaryModelRequiredError,
+  ContextWindowManager,
+  DEFAULT_COMPACTION_EFFECTIVE_MIN_SAVINGS_RATIO,
+  DEFAULT_CONTEXT_LIMITS,
+  DEFAULT_SUMMARY_MAX_INPUT_TOKENS,
+  DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS,
+  canGenerateCompactionSummary,
+  createCompactionEffectiveness,
+  createCompactionSummaryContent,
+  decideContextCompaction,
+  extractCompactionSummaryText,
+  generateSplitTurnSummary,
+  generateSummary,
+  getUsableTokenLimit,
+  isContextOverflowing,
+  planCompactionCut,
+  pruneContext,
+  pruneToolContext,
+  pruneToolContextWithReport,
+  redactSummaryText,
+  resolveContextSummaryPolicy,
+  resolveSummaryOutputTokens,
+  serializeMessagesForSummary,
+  shouldFallbackOnSummaryFailure,
+  shouldPruneContext
+} from "../chunk-NMJNN6LS.js";
+import {
+  AGENT_CONTEXT_FRAGMENT_CLOSE,
+  AGENT_CONTEXT_FRAGMENT_OPEN,
+  AGENT_CONTEXT_FRAGMENT_TAG,
+  applyAgentContextFragments,
+  applyAgentContextFragmentsWithReport,
+  createAgentContextFragmentMessage,
+  estimateConversationTokens,
+  estimateMessageTokens,
+  estimateTokens,
+  getAgentContextFragmentMetadata,
+  isAgentContextFragmentMessage,
+  isRenderedAgentContextFragment,
+  normalizeAgentContextFragment,
+  parseRenderedAgentContextFragment,
+  renderAgentContextFragment
+} from "../chunk-AAGKWUXR.js";
+export {
+  AGENT_CONTEXT_FRAGMENT_CLOSE,
+  AGENT_CONTEXT_FRAGMENT_OPEN,
+  AGENT_CONTEXT_FRAGMENT_TAG,
+  ContextSummaryModelRequiredError,
+  ContextWindowManager,
+  DEFAULT_COMPACTION_EFFECTIVE_MIN_SAVINGS_RATIO,
+  DEFAULT_CONTEXT_LIMITS,
+  DEFAULT_SUMMARY_MAX_INPUT_TOKENS,
+  DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS,
+  applyAgentContextFragments,
+  applyAgentContextFragmentsWithReport,
+  assembleModelContext,
+  canGenerateCompactionSummary,
+  createAgentContextFragmentMessage,
+  createCompactionEffectiveness,
+  createCompactionSummaryContent,
+  decideContextCompaction,
+  estimateConversationTokens,
+  estimateMessageTokens,
+  estimateTokens,
+  extractCompactionSummaryText,
+  generateSplitTurnSummary,
+  generateSummary,
+  getAgentContextFragmentMetadata,
+  getUsableTokenLimit,
+  isAgentContextFragmentMessage,
+  isContextOverflowing,
+  isRenderedAgentContextFragment,
+  normalizeAgentContextFragment,
+  parseRenderedAgentContextFragment,
+  planCompactionCut,
+  pruneContext,
+  pruneToolContext,
+  pruneToolContextWithReport,
+  redactSummaryText,
+  renderAgentContextFragment,
+  resolveContextSummaryPolicy,
+  resolveSummaryOutputTokens,
+  serializeMessagesForSummary,
+  shouldFallbackOnSummaryFailure,
+  shouldPruneContext
+};

package/dist/context/text/truncation.d.ts

@@ -0,0 +1,13 @@
+export type TextTruncationBoundary = "semantic" | "word" | "grapheme";
+export interface PrefixTruncationOptions {
+    boundary?: TextTruncationBoundary;
+    marker?: string;
+    separator?: string;
+}
+export interface MiddleTruncationOptions {
+    headRatio?: number;
+    marker?: (omittedChars: number) => string;
+}
+export declare function truncateTextPrefix(text: string, maxChars: number | undefined, options?: PrefixTruncationOptions): string;
+export declare function truncateTextMiddle(text: string, maxChars: number | undefined, options?: MiddleTruncationOptions): string;
+//# sourceMappingURL=truncation.d.ts.map

package/dist/context/text/truncation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../../../src/context/text/truncation.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAwKD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAcR;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAoCR"}

package/dist/context/window/budget.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Context window budgets.
+ *
+ * Centralizes the token formulas used by overflow detection, pruning, and
+ * summary generation. Keeping these formulas together makes it harder for the
+ * chat loop, Dapr workflow, and direct window-manager paths to drift.
+ */
+import type { CompactionEffectiveness } from "../../types/compaction.js";
+/**
+ * Context limits configuration.
+ *
+ * All values are in estimated tokens.
+ */
+export interface ContextLimits {
+    /** Maximum context window size in tokens */
+    contextWindow: number;
+    /** Reserve tokens for output generation */
+    reserveTokens: number;
+    /** Protect this many recent tokens from pruning */
+    protectedTokens: number;
+    /** Minimum tokens to trigger pruning (avoid pruning tiny contexts) */
+    pruneMinimum: number;
+}
+/**
+ * Default context limits.
+ * Based on typical 128 k context-window models.
+ */
+export declare const DEFAULT_CONTEXT_LIMITS: ContextLimits;
+/**
+ * Default summary output cap.
+ *
+ * This is intentionally conservative. Larger summaries can be enabled by
+ * configuration, but they are still clamped by the reserved output budget.
+ */
+export declare const DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS = 2000;
+/**
+ * Default cap for the serialized transcript sent to the summary model.
+ *
+ * This bounds compaction's own prompt independently from the main model's
+ * context window. It is intentionally generous enough to preserve useful
+ * technical detail while preventing old tool context from making the summary
+ * request fail.
+ */
+export declare const DEFAULT_SUMMARY_MAX_INPUT_TOKENS = 24000;
+/**
+ * Minimum proportional savings before a compaction pass is considered
+ * effective.
+ */
+export declare const DEFAULT_COMPACTION_EFFECTIVE_MIN_SAVINGS_RATIO = 0.02;
+/**
+ * Compute the usable token budget: the context window minus reserved output
+ * tokens.
+ *
+ * This is the single formula for the safe input threshold used by overflow
+ * detection, auto-compaction event emission, and step-processing limits.
+ */
+export declare function getUsableTokenLimit(limits: Pick<ContextLimits, "contextWindow" | "reserveTokens">): number;
+/**
+ * Check whether the context is overflowing.
+ *
+ * @param tokens - Current estimated token count
+ * @param limits - Context limits (defaults to 128 k window)
+ * @returns `true` if context exceeds context window minus reserve
+ */
+export declare function isContextOverflowing(tokens: number, limits?: ContextLimits): boolean;
+/**
+ * Check whether pruning should be triggered.
+ *
+ * Returns `false` when the conversation is still small enough that pruning
+ * would be wasteful (below `pruneMinimum`).
+ */
+export declare function shouldPruneContext(tokens: number, limits?: ContextLimits): boolean;
+/**
+ * Build the shared compaction-effectiveness report used by direct and durable
+ * runtimes.
+ */
+export declare function createCompactionEffectiveness(tokensBefore: number, tokensAfter: number, minSavingsRatio?: number): CompactionEffectiveness;
+export interface SummaryOutputBudgetOptions {
+    /** Estimated tokens in the messages being summarized. */
+    inputTokens: number;
+    /** Context limits for the active model. */
+    limits?: ContextLimits;
+    /**
+     * Maximum tokens the compaction summary is allowed to request.
+     *
+     * Use this as the model output cap when the provider does not expose one
+     * through the model object.
+     */
+    summaryMaxOutputTokens?: number;
+    /**
+     * Optional proportional target based on the removed content size.
+     *
+     * When unset, the resolver returns the configured cap. When set, the
+     * computed target is clamped to the configured cap and the reserved output
+     * budget.
+     */
+    summaryTargetRatio?: number;
+}
+/**
+ * Resolve the max output tokens for a compaction summary.
+ *
+ * The resolver has two safety caps:
+ * - explicit `summaryMaxOutputTokens`, defaulting to 2,000
+ * - 80% of `reserveTokens`, so summary generation cannot consume the full
+ *   output reserve needed by the next model response
+ */
+export declare function resolveSummaryOutputTokens(options: SummaryOutputBudgetOptions): number;
+//# sourceMappingURL=budget.d.ts.map

package/dist/context/window/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../../src/context/window/budget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAMzE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAKpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,OAAQ,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,8CAA8C,OAAO,CAAC;AAMnE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,eAAe,GAAG,eAAe,CAAC,GAC7D,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,aAAsC,GAC7C,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,aAAsC,GAC7C,OAAO,CAGT;AAWD;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,eAAe,GAAE,MAAuD,GACvE,uBAAuB,CAiBzB;AAMD,MAAM,WAAW,0BAA0B;IACzC,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAcD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAgBR"}

package/dist/context/window/compactor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Context compaction orchestration.
+ *
+ * Combines deterministic decisions, tool-context pruning, safe cut planning,
+ * and summary generation into one operation over a message array.
+ */
+import type { Message } from "../../types/index.js";
+import type { CompactionCutReason } from "../../types/compaction.js";
+import { type ContextLimits } from "./budget.js";
+import { type ContextCompactionDecision } from "./decision.js";
+import { type ToolContextPruneReport } from "./tool-pruning.js";
+import type { CompactionEffectiveness } from "../../types/compaction.js";
+import { type ContextSummaryPolicy, type ResolvedContextSummaryPolicy } from "./summary-policy.js";
+/**
+ * Options for {@link pruneContext}.
+ */
+export interface PruneContextOptions {
+    /** Context limits to enforce */
+    limits?: ContextLimits;
+    /** Summary behavior for conversation cuts. */
+    summary?: ContextSummaryPolicy | ResolvedContextSummaryPolicy;
+    /**
+     * Force a best-effort compaction pass after the provider reports context
+     * overflow.
+     */
+    force?: boolean;
+}
+/**
+ * Result of a pruning operation.
+ */
+export interface PruneResult {
+    /** Messages after pruning (may include a summary message) */
+    messages: Message[];
+    /** Deterministic policy decision that caused or skipped compaction */
+    decision: ContextCompactionDecision;
+    /** Measured compaction savings */
+    effectiveness: CompactionEffectiveness;
+    /** Number of messages removed */
+    removedCount: number;
+    /** Estimated tokens removed */
+    tokensRemoved: number;
+    /** Whether summarization was used */
+    summarized: boolean;
+    /** The summary content, if generated */
+    summary?: string;
+    /** Summary policy resolved for this pruning operation */
+    summaryPolicy: ResolvedContextSummaryPolicy;
+    /** Messages removed by conversation cutting, when applicable */
+    removedMessages?: Message[];
+    /** Messages kept after conversation cutting, before summary insertion */
+    keptMessages?: Message[];
+    /** Safe cut index used for conversation cutting, when applicable */
+    cutIndex?: number;
+    /** Why the cut boundary was selected */
+    cutReason?: CompactionCutReason;
+    /** Output token budget used for the summary request, if generated */
+    summaryOutputTokens?: number;
+    /** Details from the cheap tool-context pruning pass */
+    toolContext?: ToolContextPruneReport;
+}
+/**
+ * Prune a conversation to fit within context-window limits.
+ *
+ * Strategy, in order:
+ * 1. Prune old tool context without a model call.
+ * 2. If still overflowing, find a safe cut point and remove older messages.
+ * 3. If conversation history is cut, apply the configured summary policy.
+ *
+ * @param messages - Current message array
+ * @param options - Limits, model, and prompt overrides
+ * @returns A `PruneResult` with the trimmed messages
+ */
+export declare function pruneContext(messages: Message[], options?: PruneContextOptions): Promise<PruneResult>;
+//# sourceMappingURL=compactor.d.ts.map

package/dist/context/window/compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactor.d.ts","sourceRoot":"","sources":["../../../src/context/window/compactor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAEL,KAAK,aAAa,EAKnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAC;AAM7B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,oBAAoB,GAAG,4BAA4B,CAAC;IAC9D;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,sEAAsE;IACtE,QAAQ,EAAE,yBAAyB,CAAC;IACpC,kCAAkC;IAClC,aAAa,EAAE,uBAAuB,CAAC;IACvC,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,aAAa,EAAE,4BAA4B,CAAC;IAC5C,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC;IAC5B,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACtC;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CA+KtB"}

package/dist/context/window/cut-planner.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Context cut planning.
+ *
+ * Finds a safe message boundary for replacing old conversation history with a
+ * summary. The planner validates the entire kept suffix so the next model call
+ * does not receive orphaned tool results or incomplete tool-call groups.
+ */
+import type { Message } from "../../types/messages.js";
+import type { CompactionCutReason } from "../../types/compaction.js";
+/**
+ * Rich planning result for conversation cutting.
+ */
+export interface CompactionCutPlan {
+    /**
+     * Shape of the cut.
+     *
+     * `conversation` removes a contiguous conversation prefix. `split-turn-prefix`
+     * removes the early part of the active turn so the latest suffix can remain
+     * verbatim when the active turn is too large to fit as a unit.
+     */
+    kind: "conversation" | "split-turn-prefix";
+    /** Cut index (exclusive: remove messages before this index) */
+    cutIndex: number;
+    /** Messages that would be removed and summarized */
+    removedMessages: Message[];
+    /** Messages that would remain visible after the summary */
+    keptMessages: Message[];
+    /** Estimated tokens removed by the cut */
+    tokensRemoved: number;
+    /** Estimated tokens kept after the cut */
+    tokensKept: number;
+    /** Protected suffix target used while planning */
+    protectedTokens: number;
+    /** Why the cut boundary was selected */
+    reason: CompactionCutReason;
+    /** Historical messages before the active turn, used as summary input */
+    historyMessages: Message[];
+    /** Removed early messages from the active turn, used as summary input */
+    currentTurnPrefixMessages: Message[];
+    /** Index of the active turn start when `kind` is `split-turn-prefix` */
+    currentTurnStartIndex?: number;
+}
+export interface PlanCompactionCutOptions {
+    /**
+     * Allow the planner to cut inside the active turn when a normal turn-safe cut
+     * still leaves too much context.
+     */
+    allowSplitTurn?: boolean;
+    /**
+     * Desired upper bound for the kept suffix. Used only to decide whether the
+     * planner should try split-turn prefix compaction.
+     */
+    maxKeptTokens?: number;
+}
+/**
+ * Plan a safe conversation cut.
+ *
+ * The plan preserves a recent token suffix, avoids keeping orphaned tool
+ * results, and prefers boundaries where the kept suffix starts with a new user
+ * or system message. It returns the exact removed/kept slices so callers can
+ * summarize and persist without recomputing the boundary.
+ */
+export declare function planCompactionCut(messages: Message[], protectedTokens?: number, options?: PlanCompactionCutOptions): CompactionCutPlan;
+//# sourceMappingURL=cut-planner.d.ts.map

package/dist/context/window/cut-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut-planner.d.ts","sourceRoot":"","sources":["../../../src/context/window/cut-planner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAoB,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAYrE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,IAAI,EAAE,cAAc,GAAG,mBAAmB,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,wEAAwE;IACxE,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,yEAAyE;IACzE,yBAAyB,EAAE,OAAO,EAAE,CAAC;IACrC,wEAAwE;IACxE,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAuPD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,EAAE,EACnB,eAAe,GAAE,MAA+C,EAChE,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CAoInB"}

package/dist/context/window/decision.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Deterministic context compaction decisions.
+ *
+ * This module answers whether the context-window layer should attempt
+ * compaction. It does not mutate messages and never calls a model; LLM usage is
+ * reserved for the later summary-generation step after a safe cut is selected.
+ */
+import type { Message } from "../../types/messages.js";
+import { type ContextLimits } from "./budget.js";
+export type ContextCompactionDecisionReason = "below-prune-minimum" | "under-limit" | "overflow" | "forced-recovery";
+export type ContextCompactionDecisionStrategy = "none" | "tool-context-first";
+export interface ContextCompactionDecision {
+    /** Whether the compactor should run. */
+    needed: boolean;
+    /** Why this decision was made. */
+    reason: ContextCompactionDecisionReason;
+    /** First execution strategy selected by deterministic policy. */
+    strategy: ContextCompactionDecisionStrategy;
+    /** Whether the caller forced compaction after provider overflow. */
+    forced: boolean;
+    /** Whether a summary model is available if history must be cut. */
+    canSummarize: boolean;
+    /** Estimated input tokens before compaction. */
+    inputTokens: number;
+    /** Usable input limit: context window minus reserved output tokens. */
+    limit: number;
+    /** Estimated tokens above the usable limit. */
+    overflowTokens: number;
+    /** Recent token suffix protected from compaction. */
+    protectedTokens: number;
+    /** Minimum estimated context size before automatic compaction runs. */
+    pruneMinimum: number;
+}
+export interface DecideContextCompactionOptions {
+    limits?: ContextLimits;
+    force?: boolean;
+    canSummarize?: boolean;
+    inputTokens?: number;
+}
+export declare function decideContextCompaction(messages: readonly Message[], options?: DecideContextCompactionOptions): ContextCompactionDecision;
+//# sourceMappingURL=decision.d.ts.map

package/dist/context/window/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../../src/context/window/decision.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,aAAa,CAAC;AAGrB,MAAM,MAAM,+BAA+B,GACvC,qBAAqB,GACrB,aAAa,GACb,UAAU,GACV,iBAAiB,CAAC;AAEtB,MAAM,MAAM,iCAAiC,GAAG,MAAM,GAAG,oBAAoB,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,+BAA+B,CAAC;IACxC,iEAAiE;IACjE,QAAQ,EAAE,iCAAiC,CAAC;IAC5C,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,YAAY,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,OAAO,GAAE,8BAAmC,GAC3C,yBAAyB,CAkE3B"}

package/dist/context/window/estimation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Token Estimation Utilities
+ *
+ * Provides lightweight heuristic-based token counting for messages
+ * and conversations. Uses the chars/4 approximation — simple but
+ * effective for context-window planning decisions.
+ *
+ * These are *estimates*, not exact counts. For billing or hard limits,
+ * use the provider's native tokeniser instead.
+ */
+import type { Message } from "../../types/messages.js";
+import type { ModelMessage } from "ai";
+/**
+ * Estimate token count for a plain string.
+ *
+ * Uses the widely-accepted `chars / 4` heuristic.
+ *
+ * @param text - Text to estimate
+ * @returns Estimated token count (always ≥ 1 for non-empty input)
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimate token count for a single message.
+ *
+ * Handles:
+ * - Plain string content
+ * - Multi-part / multimodal arrays (text parts + images)
+ *
+ * @param message - A `Message` (internal) or `ModelMessage` (AI SDK)
+ * @returns Estimated token count
+ */
+export declare function estimateMessageTokens(message: Message | ModelMessage): number;
+/**
+ * Estimate total tokens for an entire conversation.
+ *
+ * Adds a small per-message overhead (≈ 4 tokens) for message
+ * framing (`role`, delimiters, etc.). When a recent assistant message has
+ * provider usage metadata, use it as a lower bound so planning follows the
+ * provider-observed context size instead of only the character heuristic.
+ *
+ * @param messages - Array of messages to estimate
+ * @returns Estimated total token count
+ */
+export declare function estimateConversationTokens(messages: readonly (Message | ModelMessage)[]): number;
+//# sourceMappingURL=estimation.d.ts.map

package/dist/context/window/estimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimation.d.ts","sourceRoot":"","sources":["../../../src/context/window/estimation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAMvC;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAmCD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,CAwB7E;AA4CD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,GAC5C,MAAM,CAOR"}

package/dist/context/window/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Context Management — Barrel Export
+ *
+ * Re-exports the public surface of context-window primitives while keeping the
+ * implementation split into focused files.
+ */
+export { estimateTokens, estimateMessageTokens, estimateConversationTokens, } from "./estimation.js";
+export { DEFAULT_CONTEXT_LIMITS, DEFAULT_COMPACTION_EFFECTIVE_MIN_SAVINGS_RATIO, DEFAULT_SUMMARY_MAX_INPUT_TOKENS, DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS, createCompactionEffectiveness, getUsableTokenLimit, isContextOverflowing, resolveSummaryOutputTokens, shouldPruneContext, } from "./budget.js";
+export type { ContextLimits, SummaryOutputBudgetOptions } from "./budget.js";
+export { planCompactionCut } from "./cut-planner.js";
+export type { CompactionCutPlan, PlanCompactionCutOptions, } from "./cut-planner.js";
+export { decideContextCompaction } from "./decision.js";
+export type { ContextCompactionDecision, ContextCompactionDecisionReason, ContextCompactionDecisionStrategy, DecideContextCompactionOptions, } from "./decision.js";
+export { pruneToolContext, pruneToolContextWithReport, } from "./tool-pruning.js";
+export type { ToolContextPruneReport, ToolContextPruneResult, } from "./tool-pruning.js";
+export { createCompactionSummaryContent, extractCompactionSummaryText, generateSummary, generateSplitTurnSummary, redactSummaryText, serializeMessagesForSummary, } from "./summary.js";
+export type { SplitTurnSummarizationOptions, SummarizationOptions, } from "./summary.js";
+export type { SummarySerializationOptions } from "./summary.js";
+export { pruneContext } from "./compactor.js";
+export type { PruneContextOptions, PruneResult } from "./compactor.js";
+export { ContextWindowManager } from "./manager.js";
+export type { ContextWindowStats } from "./manager.js";
+export { canGenerateCompactionSummary, ContextSummaryModelRequiredError, resolveContextSummaryPolicy, shouldFallbackOnSummaryFailure, } from "./summary-policy.js";
+export type { ContextSummaryPolicy, ResolvedContextSummaryPolicy, } from "./summary-policy.js";
+export type { ContextSummaryMode } from "../../types/compaction.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/context/window/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/window/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,8CAA8C,EAC9C,gCAAgC,EAChC,iCAAiC,EACjC,6BAA6B,EAC7B,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EACV,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EACV,yBAAyB,EACzB,+BAA+B,EAC/B,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,EAChC,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/context/window/manager.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Context Window Manager
+ *
+ * Stateful wrapper around the context-window primitives.
+ * Tracks per-session context limits and provides a single entry
+ * point for token estimation, overflow detection, and pruning.
+ */
+import type { LanguageModel, ModelMessage } from "ai";
+import type { Message } from "../../types/index.js";
+import { type ContextLimits } from "./budget.js";
+import { type PruneResult } from "./compactor.js";
+import { type ContextCompactionDecision } from "./decision.js";
+import { type ContextSummaryPolicy, type ResolvedContextSummaryPolicy } from "./summary-policy.js";
+export interface ContextWindowStats {
+    tokens: number;
+    limit: number;
+    available: number;
+    utilizationPercent: number;
+    isOverflowing: boolean;
+    shouldPrune: boolean;
+}
+/**
+ * Per-session context-window manager.
+ *
+ * Holds the active context-window limits and provides convenience
+ * methods for checking, reporting, and pruning context.
+ *
+ * @example
+ * ```typescript
+ * const ctx = new ContextWindowManager({ limits: { contextWindow: 200_000 } });
+ *
+ * if (ctx.shouldPrune(messages)) {
+ *   const result = await ctx.prune(messages);
+ *   console.log(`Removed ${result.removedCount} messages`);
+ * }
+ * ```
+ */
+export declare class ContextWindowManager {
+    private limits;
+    private activeModel?;
+    private summaryPolicy?;
+    constructor(options?: {
+        limits?: Partial<ContextLimits>;
+        /** Active agent model. Used for summaries unless `summary.model` overrides it. */
+        model?: LanguageModel;
+        summary?: ContextSummaryPolicy;
+    });
+    /** Get a copy of the current context limits. */
+    getLimits(): ContextLimits;
+    /** Update context limits (e.g. when switching models). */
+    setLimits(limits: Partial<ContextLimits>): void;
+    /** Set the active agent model used for summaries unless overridden. */
+    setModel(model: LanguageModel): void;
+    /** Set the summary policy used when conversation history must be cut. */
+    setSummaryPolicy(policy: ContextSummaryPolicy): void;
+    /** Resolve summary policy against the active agent model. */
+    getSummaryPolicy(): ResolvedContextSummaryPolicy;
+    /** Estimate total tokens for a message array. */
+    estimateTokens(messages: readonly (Message | ModelMessage)[]): number;
+    /** Check whether the context is overflowing. */
+    isOverflowing(messages: readonly (Message | ModelMessage)[]): boolean;
+    /** Check whether pruning should be triggered. */
+    shouldPrune(messages: readonly (Message | ModelMessage)[]): boolean;
+    /** Explain whether context compaction should run. */
+    decide(messages: readonly Message[], options?: {
+        force?: boolean;
+        inputTokens?: number;
+    }): ContextCompactionDecision;
+    /** Prune context to fit within limits. */
+    prune(messages: Message[], options?: {
+        force?: boolean;
+    }): Promise<PruneResult>;
+    /**
+     * Get a snapshot of token statistics.
+     *
+     * Useful for dashboards, logging, or deciding whether to prune.
+     */
+    getStats(messages: readonly (Message | ModelMessage)[]): ContextWindowStats;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/context/window/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/context/window/manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EAClC,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAC,CAAuB;gBAEjC,OAAO,CAAC,EAAE;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;QAChC,kFAAkF;QAClF,KAAK,CAAC,EAAE,aAAa,CAAC;QACtB,OAAO,CAAC,EAAE,oBAAoB,CAAC;KAChC;IAMD,gDAAgD;IAChD,SAAS,IAAI,aAAa;IAI1B,0DAA0D;IAC1D,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAI/C,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAIpC,yEAAyE;IACzE,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAIpD,6DAA6D;IAC7D,gBAAgB,IAAI,4BAA4B;IAIhD,iDAAiD;IACjD,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,GAAG,MAAM;IAIrE,gDAAgD;IAChD,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,GAAG,OAAO;IAKrE,iDAAiD;IACjD,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,GAAG,OAAO;IAKnE,qDAAqD;IACrD,MAAM,CACJ,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAClD,yBAAyB;IAU5B,0CAA0C;IACpC,KAAK,CACT,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,WAAW,CAAC;IAQvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,GAAG,kBAAkB;CAa5E"}

package/dist/context/window/summary-policy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Summary model policy for context compaction.
+ *
+ * The compaction decision and cut planner are deterministic. This policy only
+ * controls what happens after a conversation slice must be removed.
+ */
+import type { LanguageModel } from "ai";
+import type { ContextSummaryMode } from "../../types/compaction.js";
+export interface ContextSummaryPolicy {
+    /**
+     * `required` means conversation cuts must produce an LLM summary.
+     * `best-effort` allows deterministic fallback summaries if the model fails.
+     * `disabled` permits conversation cuts without LLM summarization.
+     *
+     * Default: `required`.
+     */
+    mode?: ContextSummaryMode;
+    /**
+     * Summary model override. When omitted, the active agent model is used.
+     */
+    model?: LanguageModel;
+    /** Custom summarization prompt. */
+    prompt?: string;
+    /** Maximum estimated input tokens sent to the summary model. */
+    maxInputTokens?: number;
+    /** Maximum output tokens requested for compaction summaries. */
+    maxOutputTokens?: number;
+    /**
+     * Optional proportional summary budget based on removed content size.
+     */
+    targetRatio?: number;
+}
+export interface ResolvedContextSummaryPolicy {
+    mode: ContextSummaryMode;
+    model?: LanguageModel;
+    prompt?: string;
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    targetRatio?: number;
+}
+export declare class ContextSummaryModelRequiredError extends Error {
+    constructor();
+}
+export declare function resolveContextSummaryPolicy(policy: ContextSummaryPolicy | undefined, activeModel?: LanguageModel): ResolvedContextSummaryPolicy;
+export declare function canGenerateCompactionSummary(policy: ResolvedContextSummaryPolicy): boolean;
+export declare function shouldFallbackOnSummaryFailure(options: {
+    policy: ResolvedContextSummaryPolicy;
+    force?: boolean;
+}): boolean;
+//# sourceMappingURL=summary-policy.d.ts.map

package/dist/context/window/summary-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-policy.d.ts","sourceRoot":"","sources":["../../../src/context/window/summary-policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,gCAAiC,SAAQ,KAAK;;CAO1D;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,WAAW,CAAC,EAAE,aAAa,GAC1B,4BAA4B,CAa9B;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAET;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,MAAM,EAAE,4BAA4B,CAAC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAEV"}