@almadar/agent 1.1.3 → 1.1.4

package/dist/index-wLhxy6Gb.d.ts

@@ -0,0 +1,520 @@
+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 { OrbitalSchema } from '@almadar/core';
+import '@langchain/langgraph';
+
+/**
+ * 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$1;
+}
+/**
+ * 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[]>;
+}
+
+/**
+ * Memory Orbital Schema
+ *
+ * Defines the structure for agent memory using Orbital types.
+ * This is an OrbitalSchema that represents user memory, preferences,
+ * and generation history.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The complete Memory Orbital Schema
+ * This defines the structure for storing agent memory
+ */
+declare const MemoryOrbitalSchema: OrbitalSchema;
+type UserPreference = {
+    id: string;
+    userId: string;
+    namingConvention: 'PascalCase' | 'camelCase' | 'snake_case';
+    validationStyle: 'strict' | 'minimal' | 'none';
+    preferredPatterns: string[];
+    commonEntities: string[];
+    commonTraits: string[];
+    learnedAt: Date;
+    confidence: number;
+};
+type GenerationSession = {
+    id: string;
+    userId: string;
+    threadId: string;
+    prompt: string;
+    skill: string;
+    generatedSchema?: Record<string, unknown>;
+    entities: string[];
+    patterns: string[];
+    validationResult?: {
+        valid: boolean;
+        errors: unknown[];
+    };
+    createdAt: Date;
+    completedAt?: Date;
+    success: boolean;
+};
+type ProjectContext = {
+    id: string;
+    appId: string;
+    userId: string;
+    projectName?: string;
+    description?: string;
+    existingEntities: string[];
+    conventions: string[];
+    domain: 'business' | 'ecommerce' | 'cms' | 'dashboard' | 'workflow';
+    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
+ *
+ * Manages user memory and preferences using Firestore persistence.
+ * Provides the foundation for personalized AI assistance by learning
+ * from user interactions and feedback.
+ */
+
+/**
+ * Minimal Firestore interface to avoid importing firebase-admin.
+ * These match the interfaces defined in firestore-checkpointer.ts
+ */
+interface FirestoreDb {
+    collection(path: string): FirestoreCollectionRef;
+    batch(): FirestoreBatch;
+}
+interface FirestoreCollectionRef {
+    doc(id: string): FirestoreDocRef;
+    where(field: string, op: string, value: unknown): FirestoreQuery;
+    orderBy(field: string, direction?: string): FirestoreQuery;
+    limit(n: number): FirestoreQuery;
+}
+interface FirestoreDocRef {
+    set(data: unknown): Promise<unknown>;
+    get(): Promise<FirestoreDocSnapshot>;
+    update(data: unknown): Promise<unknown>;
+    delete(): Promise<unknown>;
+}
+interface FirestoreDocSnapshot {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+}
+interface FirestoreQuery {
+    where(field: string, op: string, value: unknown): FirestoreQuery;
+    orderBy(field: string, direction?: string): FirestoreQuery;
+    limit(n: number): FirestoreQuery;
+    startAfter(doc: unknown): FirestoreQuery;
+    get(): Promise<FirestoreQuerySnapshot>;
+}
+interface FirestoreQuerySnapshot {
+    empty: boolean;
+    docs: FirestoreQueryDocSnapshot[];
+    size: number;
+}
+interface FirestoreQueryDocSnapshot {
+    data(): Record<string, unknown>;
+}
+interface FirestoreBatch {
+    set(ref: unknown, data: unknown): void;
+    delete(ref: unknown): void;
+    commit(): Promise<unknown>;
+}
+/**
+ * Options for MemoryManager
+ */
+interface MemoryManagerOptions {
+    /**
+     * Firestore database instance (injected)
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for user preferences
+     * @default 'agent_memory_users'
+     */
+    usersCollection?: string;
+    /**
+     * Collection name for generation sessions
+     * @default 'agent_memory_generations'
+     */
+    generationsCollection?: string;
+    /**
+     * Collection name for project context
+     * @default 'agent_memory_projects'
+     */
+    projectsCollection?: string;
+    /**
+     * Collection name for pattern affinity
+     * @default 'agent_memory_patterns'
+     */
+    patternsCollection?: string;
+    /**
+     * Collection name for user feedback
+     * @default 'agent_memory_feedback'
+     */
+    feedbackCollection?: string;
+}
+declare class MemoryManager {
+    private db;
+    private usersCollection;
+    private generationsCollection;
+    private projectsCollection;
+    private patternsCollection;
+    private feedbackCollection;
+    constructor(options: MemoryManagerOptions);
+    /**
+     * Get user preferences with defaults
+     */
+    getUserPreferences(userId: string): Promise<UserPreference | null>;
+    /**
+     * Update user preferences
+     */
+    updateUserPreferences(userId: string, preferences: Partial<Omit<UserPreference, 'id' | 'userId' | 'learnedAt'>>): Promise<void>;
+    /**
+     * Record a new generation session
+     */
+    recordGeneration(userId: string, session: Omit<GenerationSession, 'id' | 'userId' | 'createdAt'>): Promise<string>;
+    /**
+     * Get a specific generation session
+     */
+    getGenerationSession(sessionId: string): Promise<GenerationSession | null>;
+    /**
+     * Get generation history for a user
+     */
+    getUserGenerationHistory(userId: string, limit?: number): Promise<GenerationSession[]>;
+    /**
+     * Update generation session status
+     */
+    updateGenerationStatus(sessionId: string, status: GenerationSession['success'], validationResult?: GenerationSession['validationResult']): Promise<void>;
+    /**
+     * Get project context
+     */
+    getProjectContext(appId: string): Promise<ProjectContext | null>;
+    /**
+     * Update project context with new information
+     */
+    updateProjectContext(appId: string, update: Partial<Omit<ProjectContext, 'id' | 'appId'>>): Promise<void>;
+    /**
+     * Update pattern affinity based on usage
+     */
+    updatePatternAffinity(userId: string, patternId: string, outcome: 'success' | 'failure' | 'partial', context?: {
+        entityType?: string;
+        useCase?: string;
+    }): Promise<void>;
+    /**
+     * Get pattern affinity for a user
+     */
+    getPatternAffinity(userId: string, patternId: string): Promise<PatternAffinity | null>;
+    /**
+     * Get all patterns used by a user
+     */
+    getUserPatterns(userId: string): Promise<PatternAffinity[]>;
+    /**
+     * Record user feedback on a generation
+     */
+    recordFeedback(sessionId: string, feedback: Omit<UserFeedback, 'feedbackId' | 'sessionId' | 'timestamp'>): Promise<void>;
+    /**
+     * Get feedback for a session
+     */
+    getSessionFeedback(sessionId: string): Promise<UserFeedback[]>;
+    private parsePreference;
+    private serializePreference;
+    private parseSession;
+    private serializeSession;
+    private parseContext;
+    private serializeContext;
+}
+
+/**
+ * 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;
+    };
+    /** Optional: Memory manager for user/project memory (GAP-001) */
+    memoryManager?: MemoryManager;
+    /** Optional: User ID for memory lookup */
+    userId?: string;
+    /** Optional: App ID for project context */
+    appId?: 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;
+    /** User preferences loaded from memory (GAP-001) */
+    userPreferences?: UserPreference | null;
+    /** Project context loaded from memory (GAP-001) */
+    projectContext?: ProjectContext | null;
+    /** Memory manager instance (GAP-001) */
+    memoryManager?: MemoryManager;
+}
+/**
+ * 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 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 };

package/dist/index.d.ts

@@ -7,7 +7,8 @@ export { DomainDocument, DomainToSchemaResult, ParseError, SchemaToDomainResult,
 import { LLMClient } from '@almadar/llm';
 export { createCompactSystemPrompt, createSystemPrompt } from './prompts/index.js';
 import { BaseMessage } from '@langchain/core/messages';
-export { EVENT_BUDGETS, SessionManager, SessionManagerOptions, Skill, SkillAgentOptions, SkillAgentResult, SkillLoader, SkillMeta, SkillRefLoader, createSkillAgent, getBudgetWarningMessage, getEventBudget, getInterruptConfig, resumeSkillAgent } from './agent/index.js';
+import { U as UserPreference, M as MemoryManager, G as GenerationSession } from './index-wLhxy6Gb.js';
+export { E as EVENT_BUDGETS, a as MemoryManagerOptions, b as MemoryOrbitalSchema, P as PatternAffinity, c as ProjectContext, S as SessionManager, d as SessionManagerOptions, e as Skill, f as SkillAgentOptions, g as SkillAgentResult, h as SkillLoader, i as SkillMeta, j as SkillRefLoader, k as UserFeedback, l as createSkillAgent, m as getBudgetWarningMessage, n as getEventBudget, o as getInterruptConfig, r as resumeSkillAgent } from './index-wLhxy6Gb.js';
 export { F as FirestoreCheckpointer, a as FirestoreCheckpointerOptions, b as FirestoreDb, c as FirestoreTimestamp, P as PersistenceMode, S as Session, d as SessionMetadata, e as SessionRecord } from './firestore-checkpointer-DxbQ10ve.js';
 export { FirestoreSessionStore, FirestoreSessionStoreOptions, FirestoreStore, FirestoreStoreOptions, MemorySessionBackend } from './persistence/index.js';
 export { RawAgentEvent, extractFileOperation, extractInterruptData, hasInterrupt, isFileOperation, isTodoUpdate, transformAgentEvent, transformAgentEventMulti } from './event-transformer/index.js';
@@ -16,6 +17,7 @@ export { D as DomainOrbitalCompleteCallback, a as DomainOrbitalEventCallback, b
 import 'zod';
 import '@langchain/core/tools';
 import '@langchain/langgraph-checkpoint';
+import '@almadar/core';
 import '@langchain/core/runnables';
 
 /**
@@ -494,4 +496,62 @@ declare function formatSummary(summary: MetricsSummary): string;
  */
 declare function analyzeFailures(failures: GenerationMetrics[]): string[];
 
-export { type ContextCompactionConfig, DEFAULT_COMPACTION_CONFIG, type DeepAgentCompleteEvent, type DeepAgentErrorEvent, type DeepAgentEvent, type DeepAgentExecutionEvent, type DeepAgentSchemaEvent, type DeepAgentStartEvent, type GenerationMetrics, MetricsCollector, type MetricsSummary, type CombinerOptions as OrbitalCombinerOptions, type CombinerResult as OrbitalCombinerResult, type OrbitalSchemaValidationResult, SubAgent, analyzeFailures, combineOrbitals, combineOrbitalsToSchema, createErrorFixerSubagent, createSchemaGeneratorSubagent, createSubagentConfigs, createSubagents, createSummaryPrompt, createTestAnalyzerSubagent, estimateCacheSavings, estimateCombineComplexity, estimateTokens, formatSummary, generateFullOrbital, isCompleteEvent, isErrorEvent, isExecutionEvent, isSchemaEvent, isStartEvent, needsCompaction, parseDeepAgentEvent };
+/**
+ * Preference Learner
+ *
+ * Uses LLM to infer user preferences from generation sessions.
+ * Leverages @almadar/llm for structured output.
+ *
+ * @packageDocumentation
+ */
+
+interface PreferenceLearnerOptions {
+    /** LLM client for inference */
+    llmClient?: LLMClient;
+    /** Memory manager for persistence */
+    memoryManager: MemoryManager;
+    /** Confidence threshold for auto-accepting preferences */
+    confidenceThreshold?: number;
+}
+interface InferredPreference {
+    /** The preference field being inferred */
+    field: keyof Omit<UserPreference, 'id' | 'userId' | 'learnedAt'>;
+    /** The inferred value */
+    value: unknown;
+    /** Confidence level (0-1) */
+    confidence: number;
+    /** Explanation of why this was inferred */
+    reasoning: string;
+}
+interface PreferenceAnalysis {
+    /** List of inferred preferences */
+    inferences: InferredPreference[];
+    /** Whether the inference is high confidence */
+    isHighConfidence: boolean;
+}
+declare class PreferenceLearner {
+    private llmClient;
+    private memoryManager;
+    private confidenceThreshold;
+    constructor(options: PreferenceLearnerOptions);
+    /**
+     * Analyze a session and infer user preferences
+     */
+    analyzeSession(session: GenerationSession): Promise<PreferenceAnalysis>;
+    /**
+     * Learn from a session and update preferences if confidence is high
+     */
+    learnFromSession(session: GenerationSession): Promise<UserPreference | null>;
+    /**
+     * Batch learn from multiple sessions
+     */
+    batchLearn(sessions: GenerationSession[]): Promise<UserPreference | null>;
+    private buildAnalysisPrompt;
+    private buildAggregatePrompt;
+    private parseAnalysisResponse;
+    private isValidNamingConvention;
+    private isValidValidationStyle;
+}
+declare function createPreferenceLearner(options: PreferenceLearnerOptions): PreferenceLearner;
+
+export { type ContextCompactionConfig, DEFAULT_COMPACTION_CONFIG, type DeepAgentCompleteEvent, type DeepAgentErrorEvent, type DeepAgentEvent, type DeepAgentExecutionEvent, type DeepAgentSchemaEvent, type DeepAgentStartEvent, type GenerationMetrics, GenerationSession, type InferredPreference, MemoryManager, MetricsCollector, type MetricsSummary, type CombinerOptions as OrbitalCombinerOptions, type CombinerResult as OrbitalCombinerResult, type OrbitalSchemaValidationResult, type PreferenceAnalysis, PreferenceLearner, type PreferenceLearnerOptions, SubAgent, UserPreference, analyzeFailures, combineOrbitals, combineOrbitalsToSchema, createErrorFixerSubagent, createPreferenceLearner, createSchemaGeneratorSubagent, createSubagentConfigs, createSubagents, createSummaryPrompt, createTestAnalyzerSubagent, estimateCacheSavings, estimateCombineComplexity, estimateTokens, formatSummary, generateFullOrbital, isCompleteEvent, isErrorEvent, isExecutionEvent, isSchemaEvent, isStartEvent, needsCompaction, parseDeepAgentEvent };