@cuylabs/agent-core 4.9.0 → 5.0.0

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

@@ -0,0 +1,89 @@
+/**
+ * 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, CompactionEffectiveness, CompactionReason, CompactionTrigger, ToolContextPrunePolicy } from "../../types/compaction.js";
+import { type ContextTokenEstimator } from "./estimation.js";
+import { type ContextLimits } from "./budget.js";
+import { type ContextCompactionDecision } from "./decision.js";
+import { type ToolContextPruneReport } from "./tool-pruning.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;
+    /** Cheap tool-context pruning controls. */
+    toolPruning?: {
+        /** Set false to skip old tool-output and tool-argument pruning. */
+        enabled?: boolean;
+        /** Policy for deciding how aggressively old tool context is compacted. */
+        policy?: ToolContextPrunePolicy;
+    };
+    /**
+     * Force a best-effort compaction pass after the provider reports context
+     * overflow.
+     */
+    force?: boolean;
+    /** Lifecycle source that requested this compaction pass. */
+    trigger?: CompactionTrigger;
+    /** Operational reason for the pass. */
+    reason?: CompactionReason;
+    /** Optional model-aware token estimator for context-window planning. */
+    tokenEstimator?: ContextTokenEstimator;
+}
+/**
+ * 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;
+    /** Existing handoff summary incorporated into the generated summary, if any */
+    previousSummary?: 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,EACV,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AACzB,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,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,2CAA2C;IAC3C,WAAW,CAAC,EAAE;QACZ,mEAAmE;QACnE,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0EAA0E;QAC1E,MAAM,CAAC,EAAE,sBAAsB,CAAC;KACjC,CAAC;IACF;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,uCAAuC;IACvC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,wEAAwE;IACxE,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;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,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,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,CAmMtB"}

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

@@ -0,0 +1,67 @@
+/**
+ * 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";
+import { type ContextTokenEstimator } from "./estimation.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;
+    /** Optional model-aware token estimator for cut planning. */
+    tokenEstimator?: ContextTokenEstimator;
+}
+/**
+ * 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;AAErE,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,iBAAiB,CAAC;AAOzB;;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;IACvB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;AA4PD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,EAAE,EACnB,eAAe,GAAE,MAA+C,EAChE,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CA8JnB"}

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

@@ -0,0 +1,50 @@
+/**
+ * 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 { CompactionReason, CompactionTrigger } from "../../types/compaction.js";
+import { type ContextLimits } from "./budget.js";
+import { type ContextTokenEstimator } from "./estimation.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;
+    /** Lifecycle source that requested this decision. */
+    trigger?: CompactionTrigger;
+    /** Operational reason for running compaction. */
+    compactionReason?: CompactionReason;
+    /** Whether a summary model is available if history must be cut. */
+    canSummarize: boolean;
+    /** Estimated input tokens before compaction. */
+    inputTokens: number;
+    /** Token threshold that starts compaction for this decision. */
+    limit: number;
+    /** Estimated tokens above the compaction threshold. */
+    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;
+    trigger?: CompactionTrigger;
+    reason?: CompactionReason;
+    tokenEstimator?: ContextTokenEstimator;
+}
+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,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAEzB,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,qDAAqD;IACrD,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,mEAAmE;IACnE,YAAY,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,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;IACrB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;AA2CD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,OAAO,GAAE,8BAAmC,GAC3C,yBAAyB,CAkF3B"}

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

@@ -0,0 +1,60 @@
+/**
+ * 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";
+/**
+ * Optional estimator used by context-window planning.
+ *
+ * The contract is intentionally named "estimator" instead of "tokenizer":
+ * callers may provide an exact model tokenizer, but approximations are also
+ * valid. Invalid return values are ignored and the built-in heuristic is used.
+ */
+export interface ContextTokenEstimator {
+    /** Estimate plain text. Used for message content, tool names, and arguments. */
+    estimateTextTokens?(text: string): number | undefined;
+    /** Estimate one model-visible message. Takes precedence over text estimates. */
+    estimateMessageTokens?(message: Message | ModelMessage): number | undefined;
+    /** Estimate the full message list. Takes precedence over message estimates. */
+    estimateConversationTokens?(messages: readonly (Message | ModelMessage)[]): number | undefined;
+}
+/**
+ * Estimate token count for a plain string.
+ *
+ * Uses the widely-accepted `chars / 4` heuristic.
+ *
+ * @param text - Text to estimate
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(text: string, estimator?: ContextTokenEstimator): 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, estimator?: ContextTokenEstimator): 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)[], estimator?: ContextTokenEstimator): 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;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,kBAAkB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtD,gFAAgF;IAChF,qBAAqB,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5E,+EAA+E;IAC/E,0BAA0B,CAAC,CACzB,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,GAC5C,MAAM,GAAG,SAAS,CAAC;CACvB;AAQD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,qBAAqB,GAChC,MAAM,CAKR;AAsCD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,GAAG,YAAY,EAC/B,SAAS,CAAC,EAAE,qBAAqB,GAChC,MAAM,CA6BR;AAgDD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC,EAAE,EAC7C,SAAS,CAAC,EAAE,qBAAqB,GAChC,MAAM,CAYR"}

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

@@ -0,0 +1,28 @@
+/**
+ * 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 type { ContextTokenEstimator } from "./estimation.js";
+export { DEFAULT_CONTEXT_LIMITS, DEFAULT_COMPACTION_EFFECTIVE_MIN_SAVINGS_RATIO, DEFAULT_SUMMARY_MAX_INPUT_TOKENS, DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS, createCompactionEffectiveness, getAutoCompactTokenLimit, getEffectiveContextWindow, 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 { DEFAULT_TOOL_CONTEXT_PRUNE_POLICY, pruneToolContext, pruneToolContextWithReport, } from "./tool-pruning.js";
+export type { ToolContextPruneReport, ToolContextPruneResult, } from "./tool-pruning.js";
+export type { ToolContextPrunePolicy } from "../../types/compaction.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, ContextWindowToolPruningOptions, } 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;AACzB,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EACL,sBAAsB,EACtB,8CAA8C,EAC9C,gCAAgC,EAChC,iCAAiC,EACjC,6BAA6B,EAC7B,wBAAwB,EACxB,yBAAyB,EACzB,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,iCAAiC,EACjC,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE,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,EACV,kBAAkB,EAClB,+BAA+B,GAChC,MAAM,cAAc,CAAC;AAEtB,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,113 @@
+/**
+ * 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 { CompactionReason, CompactionTrigger, ToolContextPrunePolicy } from "../../types/compaction.js";
+import { type ContextTokenEstimator } from "./estimation.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;
+    /** Threshold that starts automatic compaction. Kept as `limit` for compatibility. */
+    limit: number;
+    /** Safety-adjusted context window before reserving output tokens. */
+    effectiveContextWindow: number;
+    /** Hard model-input budget after output-token reservation. */
+    usableLimit: number;
+    /** Threshold used by automatic pruning decisions. */
+    autoCompactLimit: number;
+    available: number;
+    utilizationPercent: number;
+    isOverflowing: boolean;
+    shouldPrune: boolean;
+}
+export interface ContextWindowToolPruningOptions {
+    /** Set false to skip deterministic old tool-output and tool-argument pruning. */
+    enabled?: boolean;
+    /** Policy for deciding how aggressively old tool context is compacted. */
+    policy?: ToolContextPrunePolicy;
+}
+/**
+ * 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?;
+    private toolPruning?;
+    private tokenEstimator?;
+    constructor(options?: {
+        limits?: Partial<ContextLimits>;
+        /** Active agent model. Used for summaries unless `summary.model` overrides it. */
+        model?: LanguageModel;
+        summary?: ContextSummaryPolicy;
+        toolPruning?: ContextWindowToolPruningOptions;
+        /** Optional model-aware token estimator for context planning. */
+        tokenEstimator?: ContextTokenEstimator;
+    });
+    /** 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;
+    /** Set deterministic tool-context pruning behavior. */
+    setToolPruning(options: ContextWindowToolPruningOptions): void;
+    /** Get deterministic tool-context pruning behavior. */
+    getToolPruning(): ContextWindowToolPruningOptions | undefined;
+    /** Set the token estimator used for context-window planning. */
+    setTokenEstimator(estimator: ContextTokenEstimator | undefined): void;
+    /** Get the token estimator used for context-window planning. */
+    getTokenEstimator(): ContextTokenEstimator | undefined;
+    /** 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;
+        trigger?: CompactionTrigger;
+        reason?: CompactionReason;
+    }): ContextCompactionDecision;
+    /** Prune context to fit within limits. */
+    prune(messages: Message[], options?: {
+        force?: boolean;
+        trigger?: CompactionTrigger;
+        reason?: CompactionReason;
+        toolPruning?: ContextWindowToolPruningOptions;
+    }): 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":"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"}

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"}

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

@@ -0,0 +1,65 @@
+/**
+ * Compaction summary generation.
+ *
+ * This module is intentionally limited to serializing messages and asking a
+ * model for a summary. Boundary planning and persistence live elsewhere.
+ */
+import type { LanguageModel } from "ai";
+import type { Message } from "../../types/messages.js";
+/**
+ * Options for summary generation.
+ */
+export interface SummarizationOptions {
+    /** Model used to generate the summary */
+    model: LanguageModel;
+    /** Max estimated input tokens for serialized messages */
+    maxInputTokens?: number;
+    /** Max tokens for the summary output */
+    maxTokens?: number;
+    /** Custom summarization system prompt */
+    customPrompt?: string;
+    /** Existing handoff summary to update instead of summarizing from scratch */
+    previousSummary?: string;
+}
+export interface SplitTurnSummarizationOptions extends SummarizationOptions {
+    /** Older conversation messages removed before the active turn */
+    historyMessages: Message[];
+    /** Early active-turn messages removed while keeping the later suffix */
+    currentTurnPrefixMessages: Message[];
+}
+export interface SummarySerializationOptions {
+    /** Max estimated tokens across the whole serialized transcript */
+    maxInputTokens?: number;
+    /** Max estimated tokens per message before middle truncation */
+    maxMessageTokens?: number;
+    /**
+     * Fraction of the serialized budget reserved for the newest removed
+     * messages when the transcript is too large to include in full.
+     *
+     * Compaction summaries need both the original goal and the latest removed
+     * work nearest the kept suffix. A tail-biased default avoids spending the
+     * whole summary prompt on stale early context.
+     */
+    recentMessageRatio?: number;
+}
+export declare function createCompactionSummaryContent(summary: string): string;
+export declare function extractCompactionSummaryText(message: Message): string | undefined;
+export declare function redactSummaryText(text: string): string;
+export declare function serializeMessagesForSummary(messages: Message[], options?: SummarySerializationOptions): string;
+/**
+ * Generate a natural-language summary of a message sequence.
+ *
+ * @param messages - Messages to summarize
+ * @param options - Model and prompt configuration
+ * @returns Summary text
+ */
+export declare function generateSummary(messages: Message[], options: SummarizationOptions): Promise<string>;
+/**
+ * Generate a summary for a cut that splits the active turn.
+ *
+ * This keeps the later active-turn suffix verbatim while summarizing the
+ * removed prefix with different instructions from normal completed-history
+ * compaction.
+ */
+export declare function generateSplitTurnSummary(options: SplitTurnSummarizationOptions): Promise<string>;
+//# sourceMappingURL=summary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../../src/context/window/summary.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAExC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AASvD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,KAAK,EAAE,aAAa,CAAC;IACrB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,6BAA8B,SAAQ,oBAAoB;IACzE,iEAAiE;IACjE,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,wEAAwE;IACxE,yBAAyB,EAAE,OAAO,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAqCD,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GACf,MAAM,GAAG,SAAS,CAIpB;AAsBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQtD;AAgLD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE,2BAAgC,GACxC,MAAM,CA2BR;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,MAAM,CAAC,CAiCjB"}

package/dist/context/window/tool-pruning.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool context pruning.
+ *
+ * Performs the cheap compaction pass that does not require an LLM call:
+ * old, large tool outputs and old, large tool-call arguments outside the
+ * protected suffix are replaced with compact previews while preserving
+ * tool-call/result shape.
+ */
+import type { Message } from "../../types/index.js";
+import { type ToolContextPrunePolicy } from "../../types/compaction.js";
+import { type ContextTokenEstimator } from "./estimation.js";
+export declare const DEFAULT_TOOL_CONTEXT_PRUNE_POLICY: Required<ToolContextPrunePolicy>;
+export interface ToolContextPruneReport {
+    /** Number of tool result messages compacted. */
+    outputCompactedCount: number;
+    /** Number of assistant tool-call argument payloads compacted. */
+    argumentCompactedCount: number;
+    /** Estimated message tokens before the tool context pass. */
+    tokensBefore: number;
+    /** Estimated message tokens after the tool context pass. */
+    tokensAfter: number;
+    /** Estimated tokens removed by the tool context pass. */
+    tokensRemoved: number;
+}
+export interface ToolContextPruneResult {
+    messages: Message[];
+    report: ToolContextPruneReport;
+}
+/**
+ * Prune old, large tool context from the conversation.
+ *
+ * Prune strategy:
+ * - Walks backwards through messages
+ * - Protects recent outputs within `protectedTokens`
+ * - Skips protected tools such as `skill`
+ * - Stamps pruned messages with a `compactedAt` timestamp
+ *
+ * @param messages - Messages to prune
+ * @param protectedTokens - Recent tokens protected from pruning
+ * @param options - Extra tool names to protect
+ * @returns New message array with large tool context replaced
+ */
+export declare function pruneToolContextWithReport(messages: Message[], protectedTokens?: number, options?: {
+    /** Additional tools to protect from pruning */
+    protectedTools?: string[];
+    /** Policy for deciding how aggressively old tool context is compacted. */
+    policy?: ToolContextPrunePolicy;
+    /** Optional model-aware token estimator for tool context pruning. */
+    tokenEstimator?: ContextTokenEstimator;
+}): ToolContextPruneResult;
+/**
+ * Prune old, large tool context from the conversation.
+ *
+ * Prune strategy:
+ * - Walks backwards through messages
+ * - Protects recent outputs within `protectedTokens`
+ * - Skips protected tools such as `skill`
+ * - Stamps pruned tool-result messages with a `compactedAt` timestamp
+ *
+ * @param messages - Messages to prune
+ * @param protectedTokens - Recent tokens protected from pruning
+ * @param options - Extra tool names to protect
+ * @returns New message array with large tool context replaced
+ */
+export declare function pruneToolContext(messages: Message[], protectedTokens?: number, options?: {
+    /** Additional tools to protect from pruning */
+    protectedTools?: string[];
+    /** Policy for deciding how aggressively old tool context is compacted. */
+    policy?: ToolContextPrunePolicy;
+    /** Optional model-aware token estimator for tool context pruning. */
+    tokenEstimator?: ContextTokenEstimator;
+}): Message[];
+//# sourceMappingURL=tool-pruning.d.ts.map

package/dist/context/window/tool-pruning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-pruning.d.ts","sourceRoot":"","sources":["../../../src/context/window/tool-pruning.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,OAAO,EAER,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,iBAAiB,CAAC;AAIzB,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,sBAAsB,CAY5E,CAAC;AAEJ,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAuSD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,OAAO,EAAE,EACnB,eAAe,GAAE,MAA+C,EAChE,OAAO,CAAC,EAAE;IACR,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,qEAAqE;IACrE,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC,GACA,sBAAsB,CAwGxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,eAAe,GAAE,MAA+C,EAChE,OAAO,CAAC,EAAE;IACR,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,qEAAqE;IACrE,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC,GACA,OAAO,EAAE,CAGX"}