@almadar/agent 1.1.3 → 1.2.0

package/dist/agent/index.d.ts

@@ -1,251 +1,13 @@
-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, d as SessionMetadata, e as SessionRecord } from '../firestore-checkpointer-DxbQ10ve.js';
+export { E as EVENT_BUDGETS, S as SessionManager, e as SessionManagerOptions, f as Skill, g as SkillAgentOptions, h as SkillAgentResult, i as SkillLoader, j as SkillMeta, k as SkillRefLoader, m as createSkillAgent, p as getBudgetWarningMessage, q as getEventBudget, r as getInterruptConfig, t as resumeSkillAgent } from '../index-D-Ahuo6F.js';
 export { Command } from '@langchain/langgraph';
+export { P as PersistenceMode, S as SessionMetadata, e as SessionRecord } from '../firestore-checkpointer-CkNKXoun.js';
+import '@almadar/llm';
+import '../orbital-subagent-cNfTLdXQ.js';
 import '@langchain/core/tools';
 import 'zod';
 import '../api-types-BW_58thJ.js';
 import '@almadar/core/types';
+import '@langchain/langgraph-checkpoint';
+import '@almadar/core';
+import '@langchain/core/messages';
 import '@langchain/core/runnables';
-
-/**
- * Session Manager
- *
- * Unified session management API with pluggable persistence backends.
- * Supports in-memory (development) and Firestore (production) backends.
- */
-
-interface SessionManagerOptions {
-    /**
-     * Persistence mode.
-     * @default 'memory'
-     */
-    mode?: PersistenceMode;
-    /**
-     * Firestore database instance. Required when mode is 'firestore'.
-     */
-    firestoreDb?: FirestoreDb;
-}
-/**
- * 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;
-    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[]>;
-}
-
-/**
- * Skill-Based DeepAgent Factory
- *
- * Creates DeepAgent instances that use skills as the primary prompt source.
- * No custom system prompts - all agent behavior is defined through skills.
- *
- * Uses deepagents library primitives:
- * - createDeepAgent() for agent creation
- * - FilesystemBackend for file operations
- *
- * Skill loading is injected via SkillLoader functions, keeping this package
- * independent of any specific skill registry location.
- */
-
-/**
- * Skill definition loaded by the consumer.
- */
-interface Skill {
-    name: string;
-    description: string;
-    content: string;
-    allowedTools?: string[];
-    version?: string;
-    references: string[];
-    path?: string;
-}
-/**
- * Function to load a skill by name.
- */
-type SkillLoader = (name: string) => Skill | null;
-/**
- * Function to load a skill reference by skill name and ref name.
- */
-type SkillRefLoader = (skillName: string, refName: string) => string | null;
-/**
- * Options for creating a skill agent.
- */
-interface SkillAgentOptions {
-    /** Required: The skill(s) to use. Can be a single skill or array of skills. */
-    skill: string | string[];
-    /** Required: Working directory for the agent */
-    workDir: string;
-    /** Required: Function to load skills */
-    skillLoader: SkillLoader;
-    /** Optional: Function to load skill references */
-    skillRefLoader?: SkillRefLoader;
-    /** Optional: Thread ID for session continuity */
-    threadId?: string;
-    /** Optional: LLM provider */
-    provider?: LLMProvider;
-    /** Optional: Model name */
-    model?: string;
-    /** Optional: Enable verbose logging */
-    verbose?: boolean;
-    /** Optional: Disable human-in-the-loop interrupts (for eval/testing) */
-    noInterrupt?: boolean;
-    /** Optional: Callback for subagent events (orbital generation) */
-    onSubagentEvent?: SubagentEventCallback;
-    /** Optional: Session manager instance (shared across requests) */
-    sessionManager?: SessionManager;
-    /** Optional: Extracted requirements from analysis phase (for orbital skill) */
-    requirements?: {
-        entities?: string[];
-        states?: string[];
-        events?: string[];
-        guards?: string[];
-        pages?: string[];
-        effects?: string[];
-        rawRequirements?: string[];
-    };
-    /** Optional: GitHub integration configuration */
-    githubConfig?: {
-        /** GitHub personal access token */
-        token: string;
-        /** Repository owner (e.g., 'octocat') */
-        owner?: string;
-        /** Repository name (e.g., 'hello-world') */
-        repo?: string;
-    };
-}
-/**
- * Result from creating a skill agent.
- */
-interface SkillAgentResult {
-    /** The agent instance (from deepagents library) */
-    agent: any;
-    /** Thread ID for session resumption */
-    threadId: string;
-    /** The loaded skill(s) - primary skill when single, all skills when multiple */
-    skill: Skill;
-    /** All loaded skills (same as skill when single) */
-    skills: Skill[];
-    /** Working directory */
-    workDir: string;
-    /** Orbital tool setter for wiring SSE callback (if orbital tool enabled) */
-    setOrbitalEventCallback?: (callback: SubagentEventCallback) => void;
-    /** Orbital tool setter for wiring persistence callback */
-    setOrbitalCompleteCallback?: (callback: OrbitalCompleteCallback) => void;
-    /** Domain orbital callback for lean skill Firestore persistence */
-    setDomainCompleteCallback?: (callback: DomainOrbitalCompleteCallback) => void;
-}
-/**
- * Create a skill-based DeepAgent.
- *
- * Uses the specified skill's content as the system prompt.
- * When multiple skills are provided, the agent sees all skill descriptions
- * and can choose the appropriate one based on the user's request.
- *
- * @throws Error if any skill is not found
- */
-declare function createSkillAgent(options: SkillAgentOptions): Promise<SkillAgentResult>;
-/**
- * Resume a skill agent session.
- *
- * Loads the skill from session metadata and creates agent with same threadId.
- *
- * @throws Error if session not found
- */
-declare function resumeSkillAgent(threadId: string, options: {
-    verbose?: boolean;
-    noInterrupt?: boolean;
-    skillLoader: SkillLoader;
-    skillRefLoader?: SkillRefLoader;
-    sessionManager?: SessionManager;
-}): Promise<SkillAgentResult>;
-
-/**
- * Event Budget Configuration
- *
- * Prevents runaway agent loops with soft/hard event limits per skill.
- */
-/**
- * Event budget limits for different skills.
- * - soft: Warning threshold (agent reminded to finish up)
- * - hard: Maximum events before forced completion
- */
-declare const EVENT_BUDGETS: Record<string, {
-    soft: number;
-    hard: number;
-}>;
-/**
- * Get event budget for a skill.
- */
-declare function getEventBudget(skillName: string): {
-    soft: number;
-    hard: number;
-};
-/**
- * Generate a budget warning message to inject into the agent.
- */
-declare function getBudgetWarningMessage(eventCount: number, budget: {
-    soft: number;
-    hard: number;
-}): string | null;
-
-/**
- * Interrupt Configuration
- *
- * Human-in-the-loop configuration for agent tools.
- */
-/**
- * Skill metadata (minimal interface for interrupt config).
- */
-interface SkillMeta {
-    name: string;
-    allowedTools?: string[];
-}
-/**
- * Get interrupt configuration for a skill.
- *
- * Default: require approval for execute tool.
- * Skills can override via frontmatter (future enhancement).
- */
-declare function getInterruptConfig(_skill: SkillMeta): Record<string, boolean>;
-
-export { EVENT_BUDGETS, PersistenceMode, SessionManager, type SessionManagerOptions, SessionMetadata, SessionRecord, type Skill, type SkillAgentOptions, type SkillAgentResult, type SkillLoader, type SkillMeta, type SkillRefLoader, createSkillAgent, getBudgetWarningMessage, getEventBudget, getInterruptConfig, resumeSkillAgent };

package/dist/agent/index.js

@@ -3258,9 +3258,13 @@ var SessionManager = class {
   constructor(options = {}) {
     this.firestoreCheckpointer = null;
     this.firestoreSessionStore = null;
+    this.memoryManager = null;
+    this.compactionConfig = null;
     this.mode = options.mode ?? "memory";
     this.memoryBackend = new MemorySessionBackend();
     this.memoryCheckpointers = /* @__PURE__ */ new Map();
+    this.memoryManager = options.memoryManager ?? null;
+    this.compactionConfig = options.compactionConfig ?? null;
     if (this.mode === "firestore" && options.firestoreDb) {
       this.firestoreCheckpointer = new FirestoreCheckpointer({ db: options.firestoreDb });
       this.firestoreSessionStore = new FirestoreSessionStore({ db: options.firestoreDb });
@@ -3360,6 +3364,260 @@ var SessionManager = class {
     }
     return this.memoryBackend.list();
   }
+  // ============================================================================
+  // Session → Memory Sync (GAP-002D)
+  // ============================================================================
+  /**
+   * 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
+   */
+  async syncSessionToMemory(threadId, userId, sessionData) {
+    if (!this.memoryManager) {
+      console.warn("[SessionManager] No memory manager configured, skipping session sync");
+      return;
+    }
+    const metadata = this.get(threadId);
+    if (!metadata) {
+      console.warn(`[SessionManager] Session ${threadId} not found, skipping sync`);
+      return;
+    }
+    try {
+      await this.memoryManager.recordGeneration(userId, {
+        threadId,
+        prompt: sessionData.inputDescription,
+        skill: metadata.skill,
+        generatedSchema: sessionData.generatedOrbital ? { name: sessionData.generatedOrbital } : void 0,
+        patterns: sessionData.patternsUsed ?? [],
+        entities: sessionData.entities ?? [],
+        success: sessionData.success,
+        completedAt: /* @__PURE__ */ new Date()
+      });
+      if (sessionData.patternsUsed && sessionData.patternsUsed.length > 0) {
+        await this.memoryManager.updateUserPreferences(userId, {
+          preferredPatterns: sessionData.patternsUsed,
+          commonEntities: sessionData.entities
+        });
+      }
+      if (sessionData.entities && sessionData.entities.length > 0) {
+        await this.memoryManager.updateProjectContext(sessionData.appId, {
+          userId,
+          existingEntities: sessionData.entities
+        });
+      }
+      console.log(`[SessionManager] Session ${threadId} synced to memory for user ${userId}`);
+    } catch (error) {
+      console.error("[SessionManager] Failed to sync session to memory:", error);
+    }
+  }
+  // ============================================================================
+  // Interrupt → Memory Sync (GAP-003: Interrupt Memory)
+  // ============================================================================
+  /**
+   * 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
+   */
+  async recordInterruptDecision(sessionId, userId, interruptData) {
+    if (!this.memoryManager) {
+      console.warn("[SessionManager] No memory manager configured, skipping interrupt sync");
+      return;
+    }
+    try {
+      await this.memoryManager.recordInterruptDecision(sessionId, userId, interruptData);
+      console.log(`[SessionManager] Interrupt recorded for user ${userId}: ${interruptData.toolName} ${interruptData.decision}`);
+    } catch (error) {
+      console.error("[SessionManager] Failed to record interrupt:", error);
+    }
+  }
+  /**
+   * Get interrupt history for a session.
+   */
+  async getSessionInterrupts(sessionId) {
+    if (!this.memoryManager) {
+      return [];
+    }
+    return this.memoryManager.getSessionInterrupts(sessionId);
+  }
+  /**
+   * Check if a tool should be auto-approved for a user.
+   */
+  async shouldAutoApproveTool(userId, toolName) {
+    if (!this.memoryManager) {
+      return false;
+    }
+    return this.memoryManager.shouldAutoApproveTool(userId, toolName);
+  }
+  // ============================================================================
+  // Checkpoint Management (GAP-004: Checkpoint → Memory)
+  // ============================================================================
+  /**
+   * 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
+   */
+  async recordCheckpoint(userId, checkpointData) {
+    if (!this.memoryManager) {
+      console.warn("[SessionManager] No memory manager configured, skipping checkpoint record");
+      return;
+    }
+    try {
+      await this.memoryManager.recordCheckpoint(userId, checkpointData);
+      console.log(`[SessionManager] Checkpoint ${checkpointData.checkpointId} recorded for user ${userId}`);
+    } catch (error) {
+      console.error("[SessionManager] Failed to record checkpoint:", error);
+    }
+  }
+  /**
+   * 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
+   */
+  async recordRollback(userId, checkpointId, reason) {
+    if (!this.memoryManager) {
+      console.warn("[SessionManager] No memory manager configured, skipping rollback record");
+      return;
+    }
+    try {
+      await this.memoryManager.recordRollback(userId, checkpointId, reason);
+      console.log(`[SessionManager] Rollback to ${checkpointId} recorded for user ${userId}`);
+    } catch (error) {
+      console.error("[SessionManager] Failed to record rollback:", error);
+    }
+  }
+  /**
+   * 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
+   */
+  async markCheckpointSuccessful(userId, checkpointId) {
+    if (!this.memoryManager) {
+      console.warn("[SessionManager] No memory manager configured, skipping success mark");
+      return;
+    }
+    try {
+      await this.memoryManager.markCheckpointSuccessful(userId, checkpointId);
+      console.log(`[SessionManager] Checkpoint ${checkpointId} marked as successful for user ${userId}`);
+    } catch (error) {
+      console.error("[SessionManager] Failed to mark checkpoint as successful:", error);
+    }
+  }
+  /**
+   * Get checkpoint history for a thread.
+   *
+   * @param threadId - The thread to get checkpoints for
+   * @returns Array of checkpoint records
+   */
+  async getThreadCheckpoints(threadId) {
+    if (!this.memoryManager) {
+      return [];
+    }
+    return this.memoryManager.getThreadCheckpoints(threadId);
+  }
+  /**
+   * 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
+   */
+  async getProblemCheckpoints(userId, minRollbackCount = 2) {
+    if (!this.memoryManager) {
+      return [];
+    }
+    return this.memoryManager.getProblemCheckpoints(userId, minRollbackCount);
+  }
+  // ============================================================================
+  // Context Compaction (GAP-005)
+  // ============================================================================
+  /**
+   * Get the context compaction configuration.
+   * @returns The compaction configuration or null if not configured.
+   */
+  getCompactionConfig() {
+    return this.compactionConfig;
+  }
+  /**
+   * 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) {
+    if (!this.compactionConfig) {
+      return false;
+    }
+    const totalChars = messages.reduce((sum, msg) => {
+      const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+      return sum + content.length;
+    }, 0);
+    const estimatedTokens = totalChars / 4;
+    const threshold = this.compactionConfig.maxTokens ?? 15e4;
+    return estimatedTokens > threshold * 0.8;
+  }
+  /**
+   * 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
+   */
+  async recordCompaction(threadId, originalMessageCount, compactedMessageCount, reason) {
+    if (!this.memoryManager) {
+      console.warn("[SessionManager] No memory manager configured, skipping compaction record");
+      return;
+    }
+    try {
+      const metadata = this.get(threadId);
+      if (metadata) {
+        const compactionInfo = {
+          timestamp: Date.now(),
+          originalMessageCount,
+          compactedMessageCount,
+          reason: reason ?? "token_limit"
+        };
+        const meta = metadata;
+        const existingCompactions = meta.compactions ?? [];
+        meta.compactions = [...existingCompactions, compactionInfo];
+        this.store(threadId, metadata);
+      }
+      console.log(`[SessionManager] Compaction recorded for ${threadId}: ${originalMessageCount} \u2192 ${compactedMessageCount} messages`);
+    } catch (error) {
+      console.error("[SessionManager] Failed to record compaction:", error);
+    }
+  }
+  /**
+   * Get compaction history for a session.
+   *
+   * @param threadId - The session thread ID
+   * @returns Array of compaction events
+   */
+  getCompactionHistory(threadId) {
+    const metadata = this.get(threadId);
+    if (!metadata) {
+      return [];
+    }
+    const meta = metadata;
+    return meta.compactions ?? [];
+  }
 };
 
 // src/agent/interrupt-config.ts
@@ -3520,10 +3778,30 @@ ${skillSummaries}
 
 ${skillContents}`;
   }
+  let userPreferences = null;
+  let projectContext = null;
+  if (options.memoryManager && options.userId) {
+    try {
+      userPreferences = await options.memoryManager.getUserPreferences(options.userId);
+      if (userPreferences && verbose) {
+        console.log(`[SkillAgent] Loaded user preferences: ${userPreferences.namingConvention} naming, ${userPreferences.preferredPatterns.length} patterns`);
+      }
+      if (options.appId) {
+        projectContext = await options.memoryManager.getProjectContext(options.appId);
+        if (projectContext && verbose) {
+          console.log(`[SkillAgent] Loaded project context: ${projectContext.existingEntities.length} entities`);
+        }
+      }
+    } catch (error) {
+      console.warn("[SkillAgent] Failed to load memory:", error);
+    }
+  }
+  const memoryContext = buildMemoryContext(userPreferences, projectContext);
   const systemPrompt = [
     BASE_SYSTEM_PROMPT,
     "\n## Skill Instructions\n\n" + skillInstructions,
-    references ? "\n## Reference Documentation\n\n" + references : ""
+    references ? "\n## Reference Documentation\n\n" + references : "",
+    memoryContext ? "\n## User Context\n\n" + memoryContext : ""
   ].filter(Boolean).join("\n");
   const threadId = providedThreadId || v4();
   const llmClient = createLLMClient(provider, model, verbose);
@@ -3626,9 +3904,54 @@ ${skillContents}`;
     workDir,
     setOrbitalEventCallback,
     setOrbitalCompleteCallback,
-    setDomainCompleteCallback
+    setDomainCompleteCallback,
+    userPreferences,
+    projectContext,
+    memoryManager: options.memoryManager
   };
 }
+function buildMemoryContext(userPreferences, projectContext) {
+  const sections = [];
+  if (userPreferences) {
+    const prefs = [];
+    if (userPreferences.namingConvention) {
+      prefs.push(`- Preferred naming: ${userPreferences.namingConvention}`);
+    }
+    if (userPreferences.validationStyle) {
+      prefs.push(`- Validation style: ${userPreferences.validationStyle}`);
+    }
+    if (userPreferences.preferredPatterns.length > 0) {
+      prefs.push(`- Preferred patterns: ${userPreferences.preferredPatterns.join(", ")}`);
+    }
+    if (userPreferences.commonEntities.length > 0) {
+      prefs.push(`- Commonly used entities: ${userPreferences.commonEntities.join(", ")}`);
+    }
+    if (prefs.length > 0) {
+      sections.push(`### User Preferences
+${prefs.join("\n")}`);
+    }
+  }
+  if (projectContext) {
+    const ctx = [];
+    if (projectContext.projectName) {
+      ctx.push(`- Project: ${projectContext.projectName}`);
+    }
+    if (projectContext.domain) {
+      ctx.push(`- Domain: ${projectContext.domain}`);
+    }
+    if (projectContext.existingEntities.length > 0) {
+      ctx.push(`- Existing entities: ${projectContext.existingEntities.join(", ")}`);
+    }
+    if (projectContext.conventions.length > 0) {
+      ctx.push(`- Project conventions: ${projectContext.conventions.join(", ")}`);
+    }
+    if (ctx.length > 0) {
+      sections.push(`### Project Context
+${ctx.join("\n")}`);
+    }
+  }
+  return sections.length > 0 ? sections.join("\n\n") : null;
+}
 async function resumeSkillAgent(threadId, options) {
   const sessions = options.sessionManager ?? getDefaultSessionManager();
   const metadata = sessions.get(threadId);