goatchain 0.0.31 → 0.0.33

package/dist/middleware/contextCompressionMiddleware.d.ts

@@ -3,48 +3,196 @@ import type { AgentLoopState } from '../agent/types';
 import type { ModelClient } from '../model';
 import type { StateStore } from '../state/stateStore';
 import type { Message } from '../types';
+/**
+ * Configuration options for context compression middleware.
+ */
 export interface ContextCompressionOptions {
-    contextLength: number;
+    /**
+     * Maximum token limit for the model (e.g., 128000 for GPT-4).
+     * - Tool compression triggers at 50% (maxTokens * 0.5)
+     * - Summary compression triggers at 80% (maxTokens * 0.8)
+     */
+    maxTokens: number;
+    /**
+     * Compression strategy mode.
+     * - `smart` (default): use adaptive boundaries and multi-stage compression.
+     * - `legacy`: keep historical behavior based on `protectedTurns` and tool params.
+     */
+    compressionMode?: 'smart' | 'legacy';
+    /**
+     * Number of recent conversation turns to always protect (default: 2, legacy mode only).
+     * A turn is a user message + assistant response pair.
+     * The last N turns will always be preserved from summary compression.
+     * Tool compression ignores this setting and only preserves tool results from
+     * the most recent completed turn.
+     *
+     * @deprecated Use smart mode (default) instead.
+     */
+    protectedTurns?: number;
+    /**
+     * Model to use for generating summaries.
+     */
+    model: ModelClient;
+    /**
+     * State store for persisting compression state.
+     */
+    stateStore: StateStore;
+    /**
+     * Tool compression target (default: 0.45, meaning compress to 45% of maxTokens).
+     * When tool compression is triggered at 50%, it will compress until reaching this target.
+     *
+     * @deprecated Use smart mode (default) instead.
+     */
+    toolCompressionTarget?: number;
+    /**
+     * Minimum number of recent tool results to keep (default: 5, legacy mode only).
+     * The most recent N tool results will be protected from compression.
+     *
+     * @deprecated Use smart mode (default) instead.
+     */
+    minKeepToolResults?: number;
+    /**
+     * Enable logging compression events to a file in the current working directory.
+     * If enabled, logs will be appended to 'compression-logs.jsonl' in JSONL format.
+     */
+    enableLogging?: boolean;
+    /**
+     * Custom log file path (relative to cwd or absolute).
+     * Default: 'compression-logs.jsonl'
+     */
+    logFilePath?: string;
+    /**
+     * Token limit of the model used for summarization.
+     * Used to determine when chunked summarization is needed.
+     * When the content to summarize exceeds this limit, the middleware
+     * automatically splits it into chunks and summarizes sequentially.
+     * Defaults to maxTokens if not specified.
+     */
+    summaryModelMaxTokens?: number;
+    /**
+     * Maximum characters per individual message when formatting for summary.
+     * More aggressive truncation reduces the chance of needing chunked summarization.
+     * Applies to tool outputs, user messages, and assistant messages.
+     * Default: 3000
+     */
+    maxMessageCharsForSummary?: number;
 }
+/**
+ * Options for manual compression.
+ */
 export interface ManualCompressionOptions {
+    /**
+     * Session ID for the compression.
+     */
     sessionId: string;
+    /**
+     * Full messages from the session (including all history).
+     * These should be the complete, uncompressed messages.
+     */
     fullMessages: Message[];
+    /**
+     * Model to use for generating summary.
+     */
     model: ModelClient;
+    /**
+     * State store for persisting compression state.
+     */
     stateStore: StateStore;
-    contextLength: number;
+    /**
+     * Custom prompt for summary generation (optional).
+     * If not provided, uses DEFAULT_SUMMARY_PROMPT.
+     */
+    summaryPrompt?: string;
+    /**
+     * Enable logging compression events to a file.
+     */
+    enableLogging?: boolean;
+    /**
+     * Custom log file path (relative to cwd or absolute).
+     * Default: 'compression-logs.jsonl'
+     */
+    logFilePath?: string;
+    /**
+     * Token limit of the model used for summarization.
+     * Used to determine when chunked summarization is needed.
+     * Defaults to 128000 if not specified.
+     */
+    summaryModelMaxTokens?: number;
+    /**
+     * Maximum characters per individual message when formatting for summary.
+     * Default: 3000
+     */
+    maxMessageCharsForSummary?: number;
 }
+/**
+ * Result of manual compression.
+ */
 export interface ManualCompressionResult {
+    /**
+     * Generated summary.
+     */
     summary: string;
+    /**
+     * Number of messages processed.
+     */
     messageCount: number;
+    /**
+     * Number of tool outputs found.
+     */
     toolOutputCount: number;
+    /**
+     * Committed compressed working view including the system message.
+     */
     compressedMessages: Message[];
 }
+/**
+ * Statistics about the compression operation.
+ */
 export interface CompressionStats {
+    /** Token count before compression */
     tokensBefore: number;
+    /** Token count after compression */
     tokensAfter: number;
+    /** Number of tool outputs that were cleared */
     clearedToolOutputs: number;
+    /** Number of messages that were removed by summarization */
     removedMessages: number;
+    /** Whether a summary was generated */
     summaryGenerated: boolean;
+    /** Timestamp when this compression occurred */
     timestamp: number;
 }
-export type CompressionTraceStage = 'stage1' | 'stage2' | 'stage3' | 'stage4';
-export interface CompressionTraceSnapshot {
-    sessionId: string;
-    mode: CompressionMode;
-    stage: CompressionTraceStage;
-    contextLength: number;
-    triggerThreshold: number;
-    targetTokens: number;
-    tokens: number;
-    messages: Message[];
-    rawMessages: Message[];
-    summary: string;
-    coveredMessageCount: number;
-    clearedToolOutputs: number;
-    removedMessages: number;
-    summaryGenerated: boolean;
-}
-type CompressionMode = 'auto' | 'manual';
+/**
+ * Create a context compression middleware.
+ *
+ * This middleware automatically compresses conversation history.
+ *
+ * Smart mode uses a target-driven flow:
+ * - Triggers summary compression near 80% of maxTokens
+ * - Compresses toward a low-water target near 30% in the same iteration
+ * - Bounds the persisted rolling summary so it cannot silently grow forever
+ * - Applies cooldown to avoid repeated re-summary on tiny growth
+ * - Bypasses cooldown in emergency overflow cases, then hard-fails before model
+ *   invocation if the prompt still cannot fit within maxTokens
+ *
+ * Legacy mode keeps the historical protected-turn / protected-tool behavior.
+ *
+ * @param options - Compression configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```ts
+ * const agent = new Agent({ model, stateStore, ... })
+ *
+ * agent.use(createContextCompressionMiddleware({
+ *   maxTokens: 128000,
+ *   model: model,
+ *   stateStore: agent.stateStore,
+ * }))
+ * ```
+ */
 export declare function createContextCompressionMiddleware(options: ContextCompressionOptions): Middleware<AgentLoopState>;
+/**
+ * Manually compress a session by generating a summary from full message history.
+ */
 export declare function compressSessionManually(options: ManualCompressionOptions): Promise<ManualCompressionResult>;
-export {};

package/dist/state/types.d.ts

@@ -60,12 +60,64 @@ export interface CompressedMessagesSnapshot {
  * allowing the middleware to restore its state after a restart.
  */
 export interface CompressionState {
+    /**
+     * Statistics from the last compression operation.
+     */
     lastStats?: CompressionStats;
+    /**
+     * History of all compression operations.
+     */
+    history: CompressionStats[];
+    /**
+     * Rolling summary content from summarized messages.
+     * This can be used when resuming from a checkpoint to provide context.
+     */
     summary?: string;
-    coveredMessageCount?: number;
-    baseRawSignature?: string;
-    baseRawMessageCount?: number;
+    /**
+     * Timestamp of the last smart-mode summary compression (ms).
+     */
+    lastSummaryAt?: number;
+    /**
+     * Estimated token count before the last persisted summary compression.
+     */
+    lastSummaryInputTokens?: number;
+    /**
+     * Estimated token count for the persisted summary view after the last summary
+     * compression, before any temporary tool-output clearing for the live LLM call.
+     */
+    lastSummaryOutputTokens?: number;
+    /**
+     * Number of messages removed by the last persisted summary compression.
+     */
+    lastSummaryRemovedMessages?: number;
+    /**
+     * Whether the persisted summary was rewritten to fit the bounded summary budget.
+     */
+    lastSummaryRewriteApplied?: boolean;
+    /**
+     * Last update timestamp (ms).
+     */
     updatedAt: number;
+    /**
+     * Record of which messages were compressed (removed) in the last summary compression.
+     * Used to remove the same messages when loading the summary on session resume.
+     */
+    compressedRange?: {
+        /**
+         * Index where summarization starts (first non-system message).
+         * Messages before this index (system messages) are always kept.
+         */
+        summarizeStart: number;
+        /**
+         * Index where protected turns start (messages from this onward are kept).
+         */
+        protectedStart: number;
+        /**
+         * Total number of messages at the time of compression.
+         * Used to validate if the range is still applicable.
+         */
+        totalMessagesAtCompression: number;
+    };
 }
 /**
  * Persisted compressed working view.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "goatchain",
   "type": "module",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "workspaces": [
     "packages/*"
   ],