@superblocksteam/vite-plugin-file-sync 2.0.42-next.41 → 2.0.42-next.43

package/dist/ai-service/llm/context/caching/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Type definitions for cache strategy system.
+ */
+import type { TokenizedMessage } from "../internal-types.js";
+import type { ResolvedCachingOptions } from "../options.js";
+/**
+ * Token counts for cache calculation.
+ */
+export interface TokenCounts {
+    /** Total tokens across all context */
+    total: number;
+    /** System prompt tokens */
+    system: number;
+}
+/**
+ * Input snapshot for cache breakpoint calculation.
+ */
+export interface CacheInput {
+    /** All messages including system prompt */
+    messages: TokenizedMessage[];
+    /** Token counts */
+    tokens: TokenCounts;
+    /** Caching configuration */
+    options: ResolvedCachingOptions;
+}
+/**
+ * Available cache strategy implementations.
+ */
+export type CacheStrategyType = "quantized" | "none";
+/**
+ * Default cache strategy for new contexts.
+ */
+export declare const DEFAULT_CACHE_STRATEGY: CacheStrategyType;
+//# sourceMappingURL=types.d.ts.map

package/dist/ai-service/llm/context/caching/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,mBAAmB;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAA+B,CAAC"}

package/dist/ai-service/llm/context/caching/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for cache strategy system.
+ */
+/**
+ * Default cache strategy for new contexts.
+ */
+export const DEFAULT_CACHE_STRATEGY = "quantized";
+//# sourceMappingURL=types.js.map

package/dist/ai-service/llm/context/caching/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgCH;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,WAAW,CAAC"}

package/dist/ai-service/llm/context/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Configuration loader for context management.
+ *
+ * Supports loading context configuration from environment variables.
+ * When set, environment variable config acts as the final override.
+ */
+import type { CacheStrategyType } from "./caching/index.js";
+import type { ContextOptions, LoggingOptions } from "./types.js";
+/**
+ * Configuration schema for context management.
+ */
+export interface ContextConfig {
+    /** Context options */
+    context?: ContextOptions;
+    /** Cache strategy to use (default: 'quantized') */
+    cacheStrategy?: CacheStrategyType;
+    /** Logging configuration */
+    logging?: LoggingOptions;
+}
+/**
+ * Loads context configuration from environment variable.
+ *
+ * Checks the `SUPERBLOCKS_CLARK_CONTEXT_CONFIG` environment variable for a path
+ * to a YAML configuration file. When set, this configuration acts as the final
+ * override, taking precedence over both default constants and programmatic options.
+ *
+ * Configuration hierarchy (lowest to highest priority):
+ * 1. Default constants (see constants.ts)
+ * 2. Programmatic options passed to ContextManager
+ * 3. Environment variable configuration (this function) - **final override**
+ *
+ * @returns Parsed configuration object, or null if env var not set
+ * @throws Error if file path is set but cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * // Set environment variable
+ * // SUPERBLOCKS_CLARK_CONTEXT_CONFIG=/path/to/config.yaml
+ *
+ * const config = loadContextConfigFromEnv();
+ * if (config) {
+ *   const manager = new ContextManager({
+ *     storage,
+ *     cacheStrategy: config.cacheStrategy,
+ *     logging: config.logging,
+ *   });
+ * }
+ * ```
+ */
+export declare function loadContextConfigFromEnv(): ContextConfig | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/ai-service/llm/context/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/llm/context/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,mDAAmD;IACnD,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,4BAA4B;IAC5B,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,wBAAwB,IAAI,aAAa,GAAG,IAAI,CAsB/D"}

package/dist/ai-service/llm/context/config.js

@@ -0,0 +1,58 @@
+/**
+ * Configuration loader for context management.
+ *
+ * Supports loading context configuration from environment variables.
+ * When set, environment variable config acts as the final override.
+ */
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import YAML from "yaml";
+/**
+ * Loads context configuration from environment variable.
+ *
+ * Checks the `SUPERBLOCKS_CLARK_CONTEXT_CONFIG` environment variable for a path
+ * to a YAML configuration file. When set, this configuration acts as the final
+ * override, taking precedence over both default constants and programmatic options.
+ *
+ * Configuration hierarchy (lowest to highest priority):
+ * 1. Default constants (see constants.ts)
+ * 2. Programmatic options passed to ContextManager
+ * 3. Environment variable configuration (this function) - **final override**
+ *
+ * @returns Parsed configuration object, or null if env var not set
+ * @throws Error if file path is set but cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * // Set environment variable
+ * // SUPERBLOCKS_CLARK_CONTEXT_CONFIG=/path/to/config.yaml
+ *
+ * const config = loadContextConfigFromEnv();
+ * if (config) {
+ *   const manager = new ContextManager({
+ *     storage,
+ *     cacheStrategy: config.cacheStrategy,
+ *     logging: config.logging,
+ *   });
+ * }
+ * ```
+ */
+export function loadContextConfigFromEnv() {
+    const envPath = process.env.SUPERBLOCKS_CLARK_CONTEXT_CONFIG;
+    if (!envPath) {
+        return null;
+    }
+    const configPath = resolve(envPath);
+    if (!existsSync(configPath)) {
+        throw new Error(`SUPERBLOCKS_CLARK_CONTEXT_CONFIG points to non-existent file: ${configPath}`);
+    }
+    try {
+        const fileContent = readFileSync(configPath, "utf-8");
+        const config = YAML.parse(fileContent);
+        return config;
+    }
+    catch (error) {
+        throw new Error(`Failed to parse context config at ${configPath}: ${error}`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/ai-service/llm/context/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../src/ai-service/llm/context/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,IAAI,MAAM,MAAM,CAAC;AAgBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,wBAAwB;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,iEAAiE,UAAU,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAkB,CAAC;QACxD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,qCAAqC,UAAU,KAAK,KAAK,EAAE,CAC5D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/ai-service/llm/context/constants.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Context Management Constants
+ *
+ * These constants configure the token budget management and compaction behavior
+ * for LLM context windows. The system uses a three-level compaction strategy
+ * to maintain conversation history within token limits while preserving
+ * the most relevant information.
+ */
+/**
+ * Maximum context size in tokens.
+ *
+ * Based on Vertex AI limits (200k tokens max context, 9k tokens max response),
+ * we set a conservative limit of 185k tokens to ensure safety margin for
+ * response generation and overhead.
+ */
+export declare const DEFAULT_MAX_CONTEXT_TOKENS = 185000;
+/**
+ * Token count threshold that triggers automatic compaction as a fraction of max context size.
+ *
+ * When context size exceeds this threshold, the compaction algorithm
+ * demotes older turns to more compressed levels and drops the oldest
+ * content if necessary.
+ *
+ * Defined as a fraction of max context size.
+ */
+export declare const DEFAULT_COMPACTION_TRIGGER_FRACTION = 0.9;
+/**
+ * Target token count after compaction completes as a fraction of max context size.
+ *
+ * The compaction algorithm aims to reduce context size to this target,
+ * leaving headroom for new content before the next compaction cycle.
+ *
+ * Defined as a fraction of max context size.
+ */
+export declare const DEFAULT_COMPACTION_TARGET_FRACTION = 0.8;
+/**
+ * Budget allocation for Level 1 (L1) turns as fraction of compaction target.
+ *
+ * L1 turns represent the most recent conversation turns with full detail:
+ * - All steps preserved
+ * - Complete tool calls and results
+ * - Full message content
+ *
+ * 50% allocation ensures recent context has maximum fidelity.
+ */
+export declare const DEFAULT_L1_TARGET_FRACTION = 0.5;
+/**
+ * Budget allocation for Level 2 (L2) turns as fraction of compaction target.
+ *
+ * L2 turns use moderate compression:
+ * - Steps flattened into single response array
+ * - Tool call inputs replaced with empty objects
+ * - Tool results marked as "[tool output trimmed]"
+ *
+ * 35% allocation balances history depth with compression.
+ */
+export declare const DEFAULT_L2_TARGET_FRACTION = 0.35;
+/**
+ * Initial estimate for character-to-token conversion ratio.
+ *
+ * This is a rough heuristic that gets refined during usage based on actual
+ * token counts from the LLM provider. Typical values range from 2-5 depending
+ * on the model and text characteristics.
+ *
+ * Starting value of 3 is conservative and works reasonably for most English text.
+ */
+export declare const DEFAULT_INITIAL_CHARS_PER_TOKEN_ESTIMATE = 3;
+/**
+ * Minimum token usage required before updating charactersPerToken estimate.
+ *
+ * Small token counts (e.g., from cached responses) can produce wildly
+ * inaccurate estimates. We only update the estimate when we have substantial
+ * token usage to work with.
+ */
+export declare const DEFAULT_MIN_TOKENS_FOR_ESTIMATE_UPDATE = 1000;
+/**
+ * Valid range for charactersPerToken estimates [min, max].
+ *
+ * Estimates outside this range are rejected as unreasonable, preventing
+ * bugs or edge cases from corrupting the token counting logic.
+ */
+export declare const DEFAULT_CHARACTERS_PER_TOKEN_MIN = 2;
+export declare const DEFAULT_CHARACTERS_PER_TOKEN_MAX = 5;
+/**
+ * Number of steps to keep in active turn when compacting.
+ *
+ * At compaction time older steps are split into a separate turn to allows
+ * them to be compacted to L2. This helps avoid context overflow for long turns.
+ *
+ * Value of 3 ensures recent tool-use loops stay in high-fidelity L1 while
+ * older interactions move to compressed L2.
+ *
+ * When aggressive compaction is needed, only the last step is kept in L1.
+ */
+export declare const DEFAULT_PRIORITIZED_STEPS = 3;
+/**
+ * If false, an error will be thrown if maxTokens is exceeded after compaction.
+ */
+export declare const DEFAULT_ALLOW_OVERFLOW = true;
+/**
+ * Default settings for debug/visualization output.
+ */
+export declare const DEFAULT_VISUALIZATION_WIDTH = 120;
+export declare const DEFAULT_VISUALIZATION_MODE = "summary";
+export declare const DEFAULT_VERBOSE_LOGGING_ENABLED = true;
+//# sourceMappingURL=constants.d.ts.map

package/dist/ai-service/llm/context/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/llm/context/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC,IAAI,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,sCAAsC,OAAO,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;GAEG;AAEH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,0BAA0B,YAAY,CAAC;AACpD,eAAO,MAAM,+BAA+B,OAAO,CAAC"}

package/dist/ai-service/llm/context/constants.js

@@ -0,0 +1,106 @@
+/**
+ * Context Management Constants
+ *
+ * These constants configure the token budget management and compaction behavior
+ * for LLM context windows. The system uses a three-level compaction strategy
+ * to maintain conversation history within token limits while preserving
+ * the most relevant information.
+ */
+/**
+ * Maximum context size in tokens.
+ *
+ * Based on Vertex AI limits (200k tokens max context, 9k tokens max response),
+ * we set a conservative limit of 185k tokens to ensure safety margin for
+ * response generation and overhead.
+ */
+export const DEFAULT_MAX_CONTEXT_TOKENS = 185_000;
+/**
+ * Token count threshold that triggers automatic compaction as a fraction of max context size.
+ *
+ * When context size exceeds this threshold, the compaction algorithm
+ * demotes older turns to more compressed levels and drops the oldest
+ * content if necessary.
+ *
+ * Defined as a fraction of max context size.
+ */
+export const DEFAULT_COMPACTION_TRIGGER_FRACTION = 0.9;
+/**
+ * Target token count after compaction completes as a fraction of max context size.
+ *
+ * The compaction algorithm aims to reduce context size to this target,
+ * leaving headroom for new content before the next compaction cycle.
+ *
+ * Defined as a fraction of max context size.
+ */
+export const DEFAULT_COMPACTION_TARGET_FRACTION = 0.8;
+/**
+ * Budget allocation for Level 1 (L1) turns as fraction of compaction target.
+ *
+ * L1 turns represent the most recent conversation turns with full detail:
+ * - All steps preserved
+ * - Complete tool calls and results
+ * - Full message content
+ *
+ * 50% allocation ensures recent context has maximum fidelity.
+ */
+export const DEFAULT_L1_TARGET_FRACTION = 0.5;
+/**
+ * Budget allocation for Level 2 (L2) turns as fraction of compaction target.
+ *
+ * L2 turns use moderate compression:
+ * - Steps flattened into single response array
+ * - Tool call inputs replaced with empty objects
+ * - Tool results marked as "[tool output trimmed]"
+ *
+ * 35% allocation balances history depth with compression.
+ */
+export const DEFAULT_L2_TARGET_FRACTION = 0.35;
+/**
+ * Initial estimate for character-to-token conversion ratio.
+ *
+ * This is a rough heuristic that gets refined during usage based on actual
+ * token counts from the LLM provider. Typical values range from 2-5 depending
+ * on the model and text characteristics.
+ *
+ * Starting value of 3 is conservative and works reasonably for most English text.
+ */
+export const DEFAULT_INITIAL_CHARS_PER_TOKEN_ESTIMATE = 3;
+/**
+ * Minimum token usage required before updating charactersPerToken estimate.
+ *
+ * Small token counts (e.g., from cached responses) can produce wildly
+ * inaccurate estimates. We only update the estimate when we have substantial
+ * token usage to work with.
+ */
+export const DEFAULT_MIN_TOKENS_FOR_ESTIMATE_UPDATE = 1000;
+/**
+ * Valid range for charactersPerToken estimates [min, max].
+ *
+ * Estimates outside this range are rejected as unreasonable, preventing
+ * bugs or edge cases from corrupting the token counting logic.
+ */
+export const DEFAULT_CHARACTERS_PER_TOKEN_MIN = 2;
+export const DEFAULT_CHARACTERS_PER_TOKEN_MAX = 5;
+/**
+ * Number of steps to keep in active turn when compacting.
+ *
+ * At compaction time older steps are split into a separate turn to allows
+ * them to be compacted to L2. This helps avoid context overflow for long turns.
+ *
+ * Value of 3 ensures recent tool-use loops stay in high-fidelity L1 while
+ * older interactions move to compressed L2.
+ *
+ * When aggressive compaction is needed, only the last step is kept in L1.
+ */
+export const DEFAULT_PRIORITIZED_STEPS = 3;
+/**
+ * If false, an error will be thrown if maxTokens is exceeded after compaction.
+ */
+export const DEFAULT_ALLOW_OVERFLOW = true;
+/**
+ * Default settings for debug/visualization output.
+ */
+export const DEFAULT_VISUALIZATION_WIDTH = 120;
+export const DEFAULT_VISUALIZATION_MODE = "summary";
+export const DEFAULT_VERBOSE_LOGGING_ENABLED = true;
+//# sourceMappingURL=constants.js.map

package/dist/ai-service/llm/context/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/ai-service/llm/context/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,IAAI,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC;AAElD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C;;GAEG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,CAAC;AACpD,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAC"}

package/dist/ai-service/llm/context/context.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Main Context class for managing LLM conversation context.
+ *
+ * Responsibilities:
+ * - Maintain conversation turns across three compression levels
+ * - Automatically compact context when token limits are approached
+ * - Track and refine character-to-token estimation
+ * - Persist context state for resumption
+ *
+ * The three-level compaction strategy:
+ * - L1 (50%): Recent turns with full detail
+ * - L2 (35%): Older turns with moderate compression
+ * - L3 (15%): Oldest turns with maximum compression
+ */
+import { type CacheStrategy } from "./caching/index.js";
+import { L1Turn, L2Turn, L3Turn } from "./levels/index.js";
+import { type ResolvedContextOptions, type ResolvedLoggingOptions } from "./options.js";
+import { type RenderContextParams } from "./utils/visualization.js";
+import type { TokenizedMessage, ResponseMessage, Step, TokenizedSystemMessage } from "./internal-types.js";
+import type { ContextRecord } from "./serialization.js";
+import type { ContextOptions, LoggingOptions, ContextId } from "./types.js";
+import type { ModelMessage, UserModelMessage, LanguageModelUsage, SystemModelMessage } from "ai";
+/**
+ * Context manages conversation history with automatic compaction.
+ * Note: you generally want to use the ContextManager to obtain a Context instance.
+ */
+export declare class Context {
+    readonly id?: ContextId;
+    readonly options: ResolvedContextOptions;
+    readonly logging: ResolvedLoggingOptions;
+    systemPrompt?: TokenizedSystemMessage;
+    l3Turns: L3Turn[];
+    l2Turns: L2Turn[];
+    l1Turns: L1Turn[];
+    private onPersist?;
+    private activeTurnNumResponses;
+    private continuations;
+    private turnStartMs;
+    private _logger;
+    private cacheStrategy;
+    constructor(params: {
+        id?: ContextId;
+        options?: ContextOptions;
+        logging?: LoggingOptions;
+        onPersist?: (record: ContextRecord) => Promise<void>;
+        cacheStrategy: CacheStrategy;
+    });
+    get charsPerToken(): number;
+    private logPrefix;
+    private get logger();
+    private persist;
+    /**
+     * Seed empty context with a summary message.
+     */
+    seedIfEmpty(summary: UserModelMessage): void;
+    /**
+     * Returns all messages in order (system + L3 + L2 + L1).
+     *
+     * Messages are returned without token counts (clean ModelMessage format).
+     */
+    getMessages(): ModelMessage[];
+    /**
+     * Total token count across all context (system + all turns).
+     */
+    get tokenCount(): number;
+    /**
+     * Token count for system prompt only.
+     */
+    get systemPromptTokenCount(): number;
+    /**
+     * Currently active turn (last L1 turn if not ended).
+     */
+    get activeTurn(): L1Turn | undefined;
+    /**
+     * Currently active step within active turn.
+     */
+    get activeStep(): Step | undefined;
+    /**
+     * All turn messages (L3 + L2 + L1), excluding continuation markers.
+     */
+    get turnMessages(): TokenizedMessage[];
+    /**
+     * All messages including system prompt.
+     */
+    private get allMessages();
+    getLevelBudgets(): {
+        l1: number;
+        l2: number;
+        l3: number;
+    };
+    /**
+     * Sets the system prompt.
+     */
+    setSystemPrompt(message: SystemModelMessage): void;
+    /**
+     * Retrieves the system prompt
+     */
+    getSystemPrompt(): SystemModelMessage | undefined;
+    /**
+     * Starts a new conversation turn with a user message.
+     *
+     * @throws {UserPromptTooLargeError} If user + system exceeds maxTokens and no options.allowOverflow is false
+     */
+    startTurn(user: UserModelMessage): void;
+    /**
+     * Starts a new step within the active turn.
+     */
+    startStep(): void;
+    /**
+     * Ends the current step, adding response messages.
+     *
+     * @param responses - Assistant and/or tool messages, accumulated over the entire active turn (this is how streamText.onStepFinish provides them)
+     * @param usage - Optional token usage info for refining estimates
+     */
+    endStep(responses: ResponseMessage[], usage?: LanguageModelUsage): void;
+    /**
+     * Ends the active turn.
+     */
+    endTurn(usage?: LanguageModelUsage): void;
+    /**
+     * Updates the character-per-token estimate based on actual LLM usage.
+     */
+    private updateCharsPerTokenEstimate;
+    /**
+     * Recalculates all token counts with current estimate.
+     */
+    private recalculateTokenCounts;
+    /**
+     * Main compaction algorithm.
+     *
+     * Triggers when context exceeds compactionTrigger threshold.
+     * Demotes/drops turns to reach compactionTarget.
+     * TODO(matt): add final AI summary level
+     *
+     * @param maxTokens - Hard token limit
+     * @param lastTurnIsActive - Whether last L1 turn is active (protected from demotion)
+     */
+    private compact;
+    private onContextLimitExceeded;
+    /**
+     * Calculates budget allocations for each compression level.
+     */
+    private calculateLevelBudgets;
+    /**
+     * Compacts L1 turns to fit within target budget.
+     */
+    private compactL1ToTarget;
+    /**
+     * Compacts L2 turns to fit within target budget.
+     */
+    private compactL2ToTarget;
+    /**
+     * Compacts L3 turns to fit within target budget by dropping oldest.
+     */
+    private compactL3ToTarget;
+    private patchContinuationBeforeDrop;
+    /**
+     * Performs aggressive compaction when still over target after level-based compaction.
+     */
+    private performAggressiveCompaction;
+    /**
+     * Splits old steps from active turn into a completed L1 turn when appropriate.
+     *
+     * Strategy:
+     * - Split when turn has more than `prioritizedSteps` steps
+     * - Merge with previous split turn if it exists (via continuations map)
+     *
+     * This keeps recent steps in the active turn while moving older steps
+     * to a completed turn that can be cached and potentially compacted.
+     */
+    private splitActiveTurn;
+    /**
+     * Performs the actual split operation.
+     *
+     * If a previous split turn exists (linked via continuations), merges steps into it.
+     * Otherwise creates a new completed turn.
+     */
+    private performSplit;
+    private withTokenCount;
+    private estimateTokenCount;
+    private toModelMessage;
+    /**
+     * Removes tool-call parts from assistant messages if their results aren't present later in the context.
+     * This can happen if a tool call was made but the tool result message was never added (e.g. due to an error).
+     * Such orphaned tool calls trigger an error in some LLMs.
+     * Example error from Vertex:
+     *{ "type": "invalid_request_error", "message": "messages.2: `tool_use` ids were found without `tool_result` blocks immediately after: toolu_vrtx_014CKoGtt5B94Q4MwZZHZ8LU. Each `tool_use` block must have a corresponding `tool_result` block in the next message."}
+     */
+    private repairBrokenToolCalls;
+    /**
+     * Serializes context for persistence.
+     */
+    toRecord(): ContextRecord;
+    printState(params?: RenderContextParams): void;
+    /**
+     * Returns an ASCII representation of the context.
+     */
+    render(params?: RenderContextParams): string;
+    /**
+     * Deserializes a context from a record.
+     *
+     * @param record - Serialized context data
+     * @param params - Parameters for the context constructor
+     */
+    static fromRecord(record: ContextRecord, params: ConstructorParameters<typeof Context>[0]): Context;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/ai-service/llm/context/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/llm/context/context.ts"],"names":[],"mappings":"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"}