@superblocksteam/vite-plugin-file-sync 2.0.42 → 2.0.43-next.0

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 current system prompt (if any).
+     */
+    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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"}