@almadar/agent 1.1.4 → 1.2.1

package/dist/{firestore-checkpointer-DxbQ10ve.d.ts → firestore-checkpointer-CkNKXoun.d.ts}

@@ -181,4 +181,4 @@ declare class FirestoreCheckpointer extends BaseCheckpointSaver {
     deleteThread(threadId: string): Promise<void>;
 }
 
-export { FirestoreCheckpointer as F, type PersistenceMode as P, type Session as S, type FirestoreCheckpointerOptions as a, type FirestoreDb as b, type FirestoreTimestamp as c, type SessionMetadata as d, type SessionRecord as e };
+export { FirestoreCheckpointer as F, type PersistenceMode as P, type SessionMetadata as S, type FirestoreCheckpointerOptions as a, type FirestoreDb as b, type FirestoreTimestamp as c, type Session as d, type SessionRecord as e };

package/dist/{index-wLhxy6Gb.d.ts → index-D-Ahuo6F.d.ts}

@@ -1,72 +1,177 @@
 import { LLMProvider } from '@almadar/llm';
 import { S as SubagentEventCallback, O as OrbitalCompleteCallback, D as DomainOrbitalCompleteCallback } from './orbital-subagent-cNfTLdXQ.js';
 import { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
-import { P as PersistenceMode, b as FirestoreDb$1, d as SessionMetadata, e as SessionRecord } from './firestore-checkpointer-DxbQ10ve.js';
+import { P as PersistenceMode, b as FirestoreDb$1, S as SessionMetadata, e as SessionRecord } from './firestore-checkpointer-CkNKXoun.js';
 import { OrbitalSchema } from '@almadar/core';
+import { BaseMessage } from '@langchain/core/messages';
 import '@langchain/langgraph';
 
 /**
- * Session Manager
+ * Context Compaction for DeepAgent
  *
- * Unified session management API with pluggable persistence backends.
- * Supports in-memory (development) and Firestore (production) backends.
+ * Provides middleware to manage context length in long-running agent sessions.
+ * Uses @langchain/core's trimMessages to keep context within token limits.
+ *
+ * @packageDocumentation
  */
 
-interface SessionManagerOptions {
-    /**
-     * Persistence mode.
-     * @default 'memory'
-     */
-    mode?: PersistenceMode;
-    /**
-     * Firestore database instance. Required when mode is 'firestore'.
-     */
-    firestoreDb?: FirestoreDb$1;
-}
 /**
- * Unified session management for agent sessions.
- *
- * Handles both session metadata and LangGraph checkpointers.
+ * Configuration for context compaction.
  */
-declare class SessionManager {
-    private mode;
-    private memoryBackend;
-    private memoryCheckpointers;
-    private firestoreCheckpointer;
-    private firestoreSessionStore;
-    constructor(options?: SessionManagerOptions);
+interface ContextCompactionConfig {
     /**
-     * Get the persistence mode.
+     * Maximum number of tokens before triggering compaction.
+     * Default: 150000 (leaves headroom for Claude's 200K context)
      */
-    getMode(): PersistenceMode;
+    maxTokens?: number;
     /**
-     * Get or create a checkpointer for a session.
+     * Number of recent messages to always keep.
+     * Default: 10
      */
-    getCheckpointer(threadId: string): BaseCheckpointSaver<any>;
+    keepRecentMessages?: number;
     /**
-     * Store session metadata.
+     * Whether to include the system message in trimming.
+     * Default: false (system message is always kept)
      */
-    store(threadId: string, metadata: SessionMetadata): void;
+    includeSystem?: boolean;
     /**
-     * Get session metadata (sync, memory only).
-     */
-    get(threadId: string): SessionMetadata | undefined;
-    /**
-     * Get session metadata (async, supports Firestore).
-     */
-    getAsync(threadId: string): Promise<SessionMetadata | undefined>;
-    /**
-     * Clear a session's checkpointer and metadata.
+     * Strategy for trimming: 'first' keeps first messages, 'last' keeps last messages.
+     * Default: 'last'
      */
-    clear(threadId: string): boolean;
-    /**
-     * List all sessions (sync, memory only).
-     */
-    list(): SessionRecord[];
-    /**
-     * List all sessions (async, supports Firestore).
-     */
-    listAsync(): Promise<SessionRecord[]>;
+    strategy?: 'first' | 'last';
+}
+/**
+ * Default configuration for context compaction.
+ */
+declare const DEFAULT_COMPACTION_CONFIG: Required<ContextCompactionConfig>;
+/**
+ * Check if messages need compaction based on estimated token count.
+ */
+declare function needsCompaction(messages: BaseMessage[], threshold?: number): boolean;
+/**
+ * Create a message summarizer prompt for compacting old context.
+ */
+declare function createSummaryPrompt(messages: BaseMessage[]): string;
+/**
+ * Estimate token count for messages using character-based heuristic.
+ */
+declare function estimateTokens(messages: BaseMessage[]): number;
+
+/**
+ * Memory System Types
+ *
+ * Additional types for the memory system beyond the core orbital types.
+ */
+/**
+ * User feedback on a generation session
+ */
+interface UserFeedback {
+    /** Unique feedback ID */
+    feedbackId: string;
+    /** Session this feedback is for */
+    sessionId: string;
+    /** User who gave the feedback */
+    userId: string;
+    /** Type of feedback */
+    type: 'positive' | 'negative' | 'correction' | 'suggestion';
+    /** Optional comment */
+    comment?: string;
+    /** Suggested correction or improvement */
+    suggestion?: string;
+    /** Timestamp of feedback */
+    timestamp: Date;
+}
+/**
+ * Pattern affinity - tracks how well patterns work for a user
+ */
+interface PatternAffinity {
+    /** User ID */
+    userId: string;
+    /** Pattern ID */
+    patternId: string;
+    /** How many times used */
+    usageCount: number;
+    /** Successful uses */
+    successCount: number;
+    /** Failed uses */
+    failureCount: number;
+    /** Contexts where this pattern was used */
+    contexts?: {
+        entityType?: string;
+        useCase?: string;
+    }[];
+    /** Last time this pattern was used */
+    lastUsedAt: Date;
+    /** When tracking started */
+    createdAt: Date;
+}
+/**
+ * Checkpoint record - tracks checkpoint history for learning
+ */
+interface CheckpointRecord {
+    /** Unique checkpoint ID */
+    checkpointId: string;
+    /** Thread/session ID */
+    threadId: string;
+    /** User who owns this checkpoint */
+    userId: string;
+    /** Parent checkpoint ID (for rollback tracking) */
+    parentCheckpointId?: string;
+    /** Checkpoint metadata */
+    metadata: {
+        step?: number;
+        skill?: string;
+        status?: string;
+        [key: string]: unknown;
+    };
+    /** When checkpoint was created */
+    createdAt: Date;
+    /** Number of times rolled back to this checkpoint */
+    rollbackCount: number;
+    /** Whether this checkpoint was a successful outcome */
+    wasSuccessful: boolean;
+}
+/**
+ * Interrupt record - tracks human-in-the-loop decisions
+ */
+interface InterruptRecord {
+    /** Unique interrupt ID */
+    interruptId: string;
+    /** Session this interrupt occurred in */
+    sessionId: string;
+    /** User who made the decision */
+    userId: string;
+    /** Tool that was interrupted */
+    toolName: string;
+    /** Tool arguments that were being executed */
+    toolArgs: Record<string, unknown>;
+    /** User's decision: approved, rejected, or modified */
+    decision: 'approved' | 'rejected' | 'modified';
+    /** Modified arguments if decision was 'modified' */
+    modifiedArgs?: Record<string, unknown>;
+    /** Reason for the decision */
+    reason?: string;
+    /** Timestamp of the interrupt */
+    timestamp: Date;
+}
+/**
+ * Tool approval preferences - learned from interrupt history
+ */
+interface ToolApprovalPreference {
+    /** User ID */
+    userId: string;
+    /** Tool name */
+    toolName: string;
+    /** Auto-approve this tool in the future */
+    autoApprove: boolean;
+    /** Confidence in this preference (0-1) */
+    confidence: number;
+    /** Number of times this tool has been approved */
+    approvedCount: number;
+    /** Number of times this tool has been rejected */
+    rejectedCount: number;
+    /** Last decision timestamp */
+    lastDecisionAt: Date;
 }
 
 /**
@@ -124,55 +229,6 @@ type ProjectContext = {
     lastUpdatedAt: Date;
 };
 
-/**
- * Memory System Types
- *
- * Additional types for the memory system beyond the core orbital types.
- */
-/**
- * User feedback on a generation session
- */
-interface UserFeedback {
-    /** Unique feedback ID */
-    feedbackId: string;
-    /** Session this feedback is for */
-    sessionId: string;
-    /** User who gave the feedback */
-    userId: string;
-    /** Type of feedback */
-    type: 'positive' | 'negative' | 'correction' | 'suggestion';
-    /** Optional comment */
-    comment?: string;
-    /** Suggested correction or improvement */
-    suggestion?: string;
-    /** Timestamp of feedback */
-    timestamp: Date;
-}
-/**
- * Pattern affinity - tracks how well patterns work for a user
- */
-interface PatternAffinity {
-    /** User ID */
-    userId: string;
-    /** Pattern ID */
-    patternId: string;
-    /** How many times used */
-    usageCount: number;
-    /** Successful uses */
-    successCount: number;
-    /** Failed uses */
-    failureCount: number;
-    /** Contexts where this pattern was used */
-    contexts?: {
-        entityType?: string;
-        useCase?: string;
-    }[];
-    /** Last time this pattern was used */
-    lastUsedAt: Date;
-    /** When tracking started */
-    createdAt: Date;
-}
-
 /**
  * Memory Manager - GAP-001: Orbital Memory System
  *
@@ -258,6 +314,21 @@ interface MemoryManagerOptions {
      * @default 'agent_memory_feedback'
      */
     feedbackCollection?: string;
+    /**
+     * Collection name for interrupt records
+     * @default 'agent_memory_interrupts'
+     */
+    interruptsCollection?: string;
+    /**
+     * Collection name for tool approval preferences
+     * @default 'agent_memory_tool_preferences'
+     */
+    toolPreferencesCollection?: string;
+    /**
+     * Collection name for checkpoint records
+     * @default 'agent_memory_checkpoints'
+     */
+    checkpointsCollection?: string;
 }
 declare class MemoryManager {
     private db;
@@ -266,6 +337,9 @@ declare class MemoryManager {
     private projectsCollection;
     private patternsCollection;
     private feedbackCollection;
+    private interruptsCollection;
+    private toolPreferencesCollection;
+    private checkpointsCollection;
     constructor(options: MemoryManagerOptions);
     /**
      * Get user preferences with defaults
@@ -328,6 +402,266 @@ declare class MemoryManager {
     private serializeSession;
     private parseContext;
     private serializeContext;
+    /**
+     * Record an interrupt decision for learning
+     */
+    recordInterruptDecision(sessionId: string, userId: string, interruptData: {
+        toolName: string;
+        toolArgs: Record<string, unknown>;
+        decision: 'approved' | 'rejected' | 'modified';
+        modifiedArgs?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Get interrupt history for a session
+     */
+    getSessionInterrupts(sessionId: string): Promise<InterruptRecord[]>;
+    /**
+     * Get interrupt history for a user
+     */
+    getUserInterrupts(userId: string, limit?: number): Promise<InterruptRecord[]>;
+    /**
+     * Get tool approval preference for a user
+     */
+    getToolApprovalPreference(userId: string, toolName: string): Promise<ToolApprovalPreference | null>;
+    /**
+     * Update tool approval preference based on interrupt decisions
+     */
+    private updateToolApprovalPreference;
+    /**
+     * Get all tool approval preferences for a user
+     */
+    getUserToolPreferences(userId: string): Promise<ToolApprovalPreference[]>;
+    /**
+     * Check if a tool should be auto-approved for a user
+     */
+    shouldAutoApproveTool(userId: string, toolName: string): Promise<boolean>;
+    /**
+     * Record a checkpoint for learning
+     */
+    recordCheckpoint(userId: string, checkpointData: {
+        checkpointId: string;
+        threadId: string;
+        parentCheckpointId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Record a rollback to a checkpoint
+     */
+    recordRollback(userId: string, checkpointId: string, reason?: string): Promise<void>;
+    /**
+     * Mark a checkpoint as successful (terminal state)
+     */
+    markCheckpointSuccessful(userId: string, checkpointId: string): Promise<void>;
+    /**
+     * Get checkpoint history for a user
+     */
+    getUserCheckpoints(userId: string, limit?: number): Promise<CheckpointRecord[]>;
+    /**
+     * Get checkpoints for a thread
+     */
+    getThreadCheckpoints(threadId: string): Promise<CheckpointRecord[]>;
+    /**
+     * Get frequently rolled-back checkpoints (problem areas)
+     */
+    getProblemCheckpoints(userId: string, minRollbackCount?: number): Promise<CheckpointRecord[]>;
+    /**
+     * Get successful checkpoint patterns for learning
+     */
+    getSuccessfulCheckpoints(userId: string, limit?: number): Promise<CheckpointRecord[]>;
+}
+
+interface SessionManagerOptions {
+    /**
+     * Persistence mode.
+     * @default 'memory'
+     */
+    mode?: PersistenceMode;
+    /**
+     * Firestore database instance. Required when mode is 'firestore'.
+     */
+    firestoreDb?: FirestoreDb$1;
+    /**
+     * Memory manager for session-to-memory sync (GAP-002D).
+     * When provided, completed sessions are recorded to orbital memory.
+     */
+    memoryManager?: MemoryManager;
+    /**
+     * Context compaction configuration (GAP-005).
+     * When provided, enables automatic context length management.
+     */
+    compactionConfig?: ContextCompactionConfig;
+}
+/**
+ * Unified session management for agent sessions.
+ *
+ * Handles both session metadata and LangGraph checkpointers.
+ */
+declare class SessionManager {
+    private mode;
+    private memoryBackend;
+    private memoryCheckpointers;
+    private firestoreCheckpointer;
+    private firestoreSessionStore;
+    private memoryManager;
+    private compactionConfig;
+    constructor(options?: SessionManagerOptions);
+    /**
+     * Get the persistence mode.
+     */
+    getMode(): PersistenceMode;
+    /**
+     * Get or create a checkpointer for a session.
+     */
+    getCheckpointer(threadId: string): BaseCheckpointSaver<any>;
+    /**
+     * Store session metadata.
+     */
+    store(threadId: string, metadata: SessionMetadata): void;
+    /**
+     * Get session metadata (sync, memory only).
+     */
+    get(threadId: string): SessionMetadata | undefined;
+    /**
+     * Get session metadata (async, supports Firestore).
+     */
+    getAsync(threadId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * Clear a session's checkpointer and metadata.
+     */
+    clear(threadId: string): boolean;
+    /**
+     * List all sessions (sync, memory only).
+     */
+    list(): SessionRecord[];
+    /**
+     * List all sessions (async, supports Firestore).
+     */
+    listAsync(): Promise<SessionRecord[]>;
+    /**
+     * Sync a completed session to orbital memory.
+     * This enables the agent to learn from past sessions.
+     *
+     * @param threadId - The session thread ID
+     * @param userId - The user ID for memory association
+     * @param sessionData - Additional session data to record
+     * @returns Promise that resolves when sync is complete
+     */
+    syncSessionToMemory(threadId: string, userId: string, sessionData: {
+        appId: string;
+        inputDescription: string;
+        generatedOrbital?: string;
+        patternsUsed?: string[];
+        entities?: string[];
+        success: boolean;
+        errorMessage?: string;
+    }): Promise<void>;
+    /**
+     * Record an interrupt decision to memory.
+     * This enables learning from HITL (Human-in-the-Loop) decisions.
+     *
+     * @param sessionId - The session thread ID
+     * @param userId - The user who made the decision
+     * @param interruptData - The interrupt decision data
+     * @returns Promise that resolves when sync is complete
+     */
+    recordInterruptDecision(sessionId: string, userId: string, interruptData: {
+        toolName: string;
+        toolArgs: Record<string, unknown>;
+        decision: 'approved' | 'rejected' | 'modified';
+        modifiedArgs?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Get interrupt history for a session.
+     */
+    getSessionInterrupts(sessionId: string): Promise<InterruptRecord[]>;
+    /**
+     * Check if a tool should be auto-approved for a user.
+     */
+    shouldAutoApproveTool(userId: string, toolName: string): Promise<boolean>;
+    /**
+     * Record a checkpoint to memory for learning.
+     *
+     * @param userId - The user who owns this checkpoint
+     * @param checkpointData - Checkpoint information
+     * @returns Promise that resolves when checkpoint is recorded
+     */
+    recordCheckpoint(userId: string, checkpointData: {
+        checkpointId: string;
+        threadId: string;
+        parentCheckpointId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Record a rollback to a checkpoint.
+     *
+     * @param userId - The user who performed the rollback
+     * @param checkpointId - The checkpoint rolled back to
+     * @param reason - Optional reason for rollback
+     * @returns Promise that resolves when rollback is recorded
+     */
+    recordRollback(userId: string, checkpointId: string, reason?: string): Promise<void>;
+    /**
+     * Mark a checkpoint as successful (terminal state).
+     *
+     * @param userId - The user who owns this checkpoint
+     * @param checkpointId - The checkpoint that was successful
+     * @returns Promise that resolves when success is recorded
+     */
+    markCheckpointSuccessful(userId: string, checkpointId: string): Promise<void>;
+    /**
+     * Get checkpoint history for a thread.
+     *
+     * @param threadId - The thread to get checkpoints for
+     * @returns Array of checkpoint records
+     */
+    getThreadCheckpoints(threadId: string): Promise<CheckpointRecord[]>;
+    /**
+     * Get frequently rolled-back checkpoints (problem areas).
+     *
+     * @param userId - The user to get problem checkpoints for
+     * @param minRollbackCount - Minimum rollback count (default: 2)
+     * @returns Array of checkpoint records with rollback issues
+     */
+    getProblemCheckpoints(userId: string, minRollbackCount?: number): Promise<CheckpointRecord[]>;
+    /**
+     * Get the context compaction configuration.
+     * @returns The compaction configuration or null if not configured.
+     */
+    getCompactionConfig(): ContextCompactionConfig | null;
+    /**
+     * Check if a session's messages need compaction based on token count.
+     * Uses character-based estimation for quick checks.
+     *
+     * @param messages - Array of messages to check
+     * @returns True if compaction is recommended
+     */
+    shouldCompactMessages(messages: {
+        content: string | unknown;
+    }[]): boolean;
+    /**
+     * Record a compaction event for a session.
+     * This helps track when and why compaction occurs.
+     *
+     * @param threadId - The session thread ID
+     * @param originalMessageCount - Number of messages before compaction
+     * @param compactedMessageCount - Number of messages after compaction
+     * @param reason - Reason for compaction
+     */
+    recordCompaction(threadId: string, originalMessageCount: number, compactedMessageCount: number, reason?: string): Promise<void>;
+    /**
+     * Get compaction history for a session.
+     *
+     * @param threadId - The session thread ID
+     * @returns Array of compaction events
+     */
+    getCompactionHistory(threadId: string): Array<{
+        timestamp: number;
+        originalMessageCount: number;
+        compactedMessageCount: number;
+        reason: string;
+    }>;
 }
 
 /**
@@ -517,4 +851,4 @@ interface SkillMeta {
  */
 declare function getInterruptConfig(_skill: SkillMeta): Record<string, boolean>;
 
-export { EVENT_BUDGETS as E, type GenerationSession as G, MemoryManager as M, type PatternAffinity as P, SessionManager as S, type UserPreference as U, type MemoryManagerOptions as a, MemoryOrbitalSchema as b, type ProjectContext as c, type SessionManagerOptions as d, type Skill as e, type SkillAgentOptions as f, type SkillAgentResult as g, type SkillLoader as h, type SkillMeta as i, type SkillRefLoader as j, type UserFeedback as k, createSkillAgent as l, getBudgetWarningMessage as m, getEventBudget as n, getInterruptConfig as o, resumeSkillAgent as r };
+export { type CheckpointRecord as C, DEFAULT_COMPACTION_CONFIG as D, EVENT_BUDGETS as E, type GenerationSession as G, type InterruptRecord as I, MemoryManager as M, type PatternAffinity as P, SessionManager as S, type ToolApprovalPreference as T, type UserPreference as U, type ContextCompactionConfig as a, type MemoryManagerOptions as b, MemoryOrbitalSchema as c, type ProjectContext as d, type SessionManagerOptions as e, type Skill as f, type SkillAgentOptions as g, type SkillAgentResult as h, type SkillLoader as i, type SkillMeta as j, type SkillRefLoader as k, type UserFeedback as l, createSkillAgent as m, createSummaryPrompt as n, estimateTokens as o, getBudgetWarningMessage as p, getEventBudget as q, getInterruptConfig as r, needsCompaction as s, resumeSkillAgent as t };