@superblocksteam/vite-plugin-file-sync 2.0.42-next.5 → 2.0.42-next.51

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

@@ -0,0 +1,20 @@
+/**
+ * Provider cache configuration constants.
+ *
+ * These are the parameters for Anthropic's recent models
+ * https://docs.claude.com/en/docs/build-with-claude/prompt-caching#cache-limitations
+ */
+export const PROVIDER_CACHE_MAX_BREAKPOINTS = 4;
+export const PROVIDER_CACHE_MIN_CACHEABLE_TOKENS = 1024;
+/**
+ * Provider-specific cache control options.
+ *
+ * Different LLM providers use different formats for cache control.
+ * This maps to the appropriate format for each provider.
+ */
+export const CACHE_BREAKPOINT_PROVIDER_OPTIONS = {
+    bedrock: { cachePoint: { type: "default" } },
+    // Vertex provider uses anthropic key
+    anthropic: { cacheControl: { type: "ephemeral" } },
+};
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAChD,MAAM,CAAC,MAAM,mCAAmC,GAAG,IAAI,CAAC;AAExD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,OAAO,EAAE,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;IAC5C,qCAAqC;IACrC,SAAS,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE;CACnD,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * Factory for creating cache strategy instances.
+ */
+import type { CacheStrategy } from "./strategy.js";
+import type { CacheStrategyType } from "./types.js";
+/**
+ * Factory for creating cache strategy instances.
+ */
+export declare class CacheStrategyFactory {
+    static create(type?: CacheStrategyType): CacheStrategy;
+}
+//# sourceMappingURL=factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,MAAM,CAAC,MAAM,CACX,IAAI,GAAE,iBAA0C,GAC/C,aAAa;CASjB"}

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

@@ -0,0 +1,28 @@
+/**
+ * Factory for creating cache strategy instances.
+ */
+import { QuantizedIntervalCacheStrategy } from "./quantized-strategy.js";
+import { DEFAULT_CACHE_STRATEGY } from "./types.js";
+/**
+ * Factory for creating cache strategy instances.
+ */
+export class CacheStrategyFactory {
+    static create(type = DEFAULT_CACHE_STRATEGY) {
+        switch (type) {
+            case "none":
+                return new NoOpCacheStrategy();
+            case "quantized":
+            default:
+                return new QuantizedIntervalCacheStrategy();
+        }
+    }
+}
+/**
+ * No-op cache strategy (disables caching).
+ */
+class NoOpCacheStrategy {
+    findBreakpoints() {
+        return [];
+    }
+}
+//# sourceMappingURL=factory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAIpD;;GAEG;AACH,MAAM,OAAO,oBAAoB;IAC/B,MAAM,CAAC,MAAM,CACX,OAA0B,sBAAsB;QAEhD,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,MAAM;gBACT,OAAO,IAAI,iBAAiB,EAAE,CAAC;YACjC,KAAK,WAAW,CAAC;YACjB;gBACE,OAAO,IAAI,8BAA8B,EAAE,CAAC;QAChD,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,MAAM,iBAAiB;IACrB,eAAe;QACb,OAAO,EAAE,CAAC;IACZ,CAAC;CACF"}

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

@@ -0,0 +1,10 @@
+/**
+ * Public API exports for caching module.
+ */
+export type { CacheInput, TokenCounts, CacheStrategyType } from "./types.js";
+export { DEFAULT_CACHE_STRATEGY } from "./types.js";
+export { type CacheStrategy } from "./strategy.js";
+export { QuantizedIntervalCacheStrategy } from "./quantized-strategy.js";
+export { CacheStrategyFactory } from "./factory.js";
+export { CACHE_BREAKPOINT_PROVIDER_OPTIONS, PROVIDER_CACHE_MAX_BREAKPOINTS, PROVIDER_CACHE_MIN_CACHEABLE_TOKENS, } from "./constants.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,iCAAiC,EACjC,8BAA8B,EAC9B,mCAAmC,GACpC,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Public API exports for caching module.
+ */
+export { DEFAULT_CACHE_STRATEGY } from "./types.js";
+export {} from "./strategy.js";
+export { QuantizedIntervalCacheStrategy } from "./quantized-strategy.js";
+export { CacheStrategyFactory } from "./factory.js";
+export { CACHE_BREAKPOINT_PROVIDER_OPTIONS, PROVIDER_CACHE_MAX_BREAKPOINTS, PROVIDER_CACHE_MIN_CACHEABLE_TOKENS, } from "./constants.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAsB,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,iCAAiC,EACjC,8BAA8B,EAC9B,mCAAmC,GACpC,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * Quantized interval cache strategy implementation.
+ *
+ * Places cache breakpoints at regular intervals to maximize cache hits
+ * while respecting provider limits.
+ */
+import type { CacheStrategy } from "./strategy.js";
+import type { CacheInput } from "./types.js";
+/**
+ * Quantized interval cache strategy.
+ *
+ * Finds optimal positions for cache breakpoints in message array.
+ *
+ * Strategy:
+ * - Always place breakpoint at system prompt (index 0) if present
+ * - Divide total tokens into intervals of minCacheableTokens
+ * - Space breakpoints evenly across intervals, respecting maxBreakpoints
+ */
+export declare class QuantizedIntervalCacheStrategy implements CacheStrategy {
+    findBreakpoints(input: CacheInput): number[];
+}
+//# sourceMappingURL=quantized-strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quantized-strategy.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/quantized-strategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,YAAW,aAAa;IAClE,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE;CA+C7C"}

package/dist/ai-service/llm/context/caching/quantized-strategy.js

@@ -0,0 +1,48 @@
+/**
+ * Quantized interval cache strategy implementation.
+ *
+ * Places cache breakpoints at regular intervals to maximize cache hits
+ * while respecting provider limits.
+ */
+/**
+ * Quantized interval cache strategy.
+ *
+ * Finds optimal positions for cache breakpoints in message array.
+ *
+ * Strategy:
+ * - Always place breakpoint at system prompt (index 0) if present
+ * - Divide total tokens into intervals of minCacheableTokens
+ * - Space breakpoints evenly across intervals, respecting maxBreakpoints
+ */
+export class QuantizedIntervalCacheStrategy {
+    findBreakpoints(input) {
+        const breakpoints = [];
+        // We have maxBreakpoints total
+        let availableBreakpoints = input.options.maxBreakpoints;
+        // Always cache system prompt if present
+        if (input.tokens.system > 0) {
+            breakpoints.push(0);
+            availableBreakpoints -= 1;
+        }
+        // Calculate total tokens available for caching (exclude system from interval calc)
+        const availableTokens = input.tokens.total - input.tokens.system;
+        // How many minimum-sized intervals can we fit?
+        const intervals = Math.floor(availableTokens / input.options.minCacheableTokens);
+        // How many intervals should we skip between each breakpoint?
+        const breakpointIntervalMultiplier = Math.max(1, Math.floor(intervals / availableBreakpoints));
+        // Actual token distance between breakpoints
+        const tokensPerInterval = input.options.minCacheableTokens * breakpointIntervalMultiplier;
+        // Walk through messages and place breakpoints at regular intervals
+        let tokensUntilBreakpoint = tokensPerInterval;
+        for (let i = input.tokens.system > 0 ? 1 : 0; i < input.messages.length &&
+            breakpoints.length < input.options.maxBreakpoints; i++) {
+            tokensUntilBreakpoint -= input.messages[i].tokenCount;
+            if (tokensUntilBreakpoint <= 0) {
+                breakpoints.push(i);
+                tokensUntilBreakpoint = tokensPerInterval;
+            }
+        }
+        return breakpoints;
+    }
+}
+//# sourceMappingURL=quantized-strategy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quantized-strategy.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/quantized-strategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;;;GASG;AACH,MAAM,OAAO,8BAA8B;IACzC,eAAe,CAAC,KAAiB;QAC/B,MAAM,WAAW,GAAa,EAAE,CAAC;QAEjC,+BAA+B;QAC/B,IAAI,oBAAoB,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC;QAExD,wCAAwC;QACxC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,oBAAoB,IAAI,CAAC,CAAC;QAC5B,CAAC;QAED,mFAAmF;QACnF,MAAM,eAAe,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QAEjE,+CAA+C;QAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAC1B,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,kBAAkB,CACnD,CAAC;QAEF,6DAA6D;QAC7D,MAAM,4BAA4B,GAAG,IAAI,CAAC,GAAG,CAC3C,CAAC,EACD,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,oBAAoB,CAAC,CAC7C,CAAC;QAEF,4CAA4C;QAC5C,MAAM,iBAAiB,GACrB,KAAK,CAAC,OAAO,CAAC,kBAAkB,GAAG,4BAA4B,CAAC;QAElE,mEAAmE;QACnE,IAAI,qBAAqB,GAAG,iBAAiB,CAAC;QAC9C,KACE,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM;YACzB,WAAW,CAAC,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,EACjD,CAAC,EAAE,EACH,CAAC;YACD,qBAAqB,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,UAAU,CAAC;YACvD,IAAI,qBAAqB,IAAI,CAAC,EAAE,CAAC;gBAC/B,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACpB,qBAAqB,GAAG,iBAAiB,CAAC;YAC5C,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;CACF"}

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

@@ -0,0 +1,20 @@
+/**
+ * Cache strategy interface.
+ */
+import type { CacheInput } from "./types.js";
+/**
+ * Strategy interface for cache breakpoint placement.
+ *
+ * Enables pluggable caching algorithms while maintaining
+ * consistent integration with Context lifecycle.
+ */
+export interface CacheStrategy {
+    /**
+     * Finds optimal cache breakpoint positions.
+     *
+     * @param input - Snapshot of context state
+     * @returns Array of message indices for cache breakpoints
+     */
+    findBreakpoints(input: CacheInput): number[];
+}
+//# sourceMappingURL=strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/strategy.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;CAC9C"}

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

@@ -0,0 +1,5 @@
+/**
+ * Cache strategy interface.
+ */
+export {};
+//# sourceMappingURL=strategy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/context/caching/strategy.ts"],"names":[],"mappings":"AAAA;;GAEG"}

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