@almadar/agent 1.1.3 → 1.2.0

package/dist/index.d.ts

@@ -6,16 +6,20 @@ import { DomainContext, OrbitalSchema, Orbital, OrbitalDefinition, FullOrbitalUn
 export { DomainDocument, DomainToSchemaResult, ParseError, SchemaToDomainResult, SectionMapping, applySectionUpdate, convertDomainToSchema, convertSchemaToDomain, deleteSection } from '@almadar/core/domain-language';
 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';
-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';
+import { U as UserPreference, M as MemoryManager, G as GenerationSession } from './index-D-Ahuo6F.js';
+export { C as CheckpointRecord, a as ContextCompactionConfig, D as DEFAULT_COMPACTION_CONFIG, E as EVENT_BUDGETS, I as InterruptRecord, b as MemoryManagerOptions, c as MemoryOrbitalSchema, P as PatternAffinity, d as ProjectContext, S as SessionManager, e as SessionManagerOptions, f as Skill, g as SkillAgentOptions, h as SkillAgentResult, i as SkillLoader, j as SkillMeta, k as SkillRefLoader, T as ToolApprovalPreference, l as UserFeedback, m as createSkillAgent, n as createSummaryPrompt, o as estimateTokens, p as getBudgetWarningMessage, q as getEventBudget, r as getInterruptConfig, s as needsCompaction, t as resumeSkillAgent } from './index-D-Ahuo6F.js';
+import { S as SessionMetadata } from './firestore-checkpointer-CkNKXoun.js';
+export { F as FirestoreCheckpointer, a as FirestoreCheckpointerOptions, b as FirestoreDb, c as FirestoreTimestamp, P as PersistenceMode, d as Session, e as SessionRecord } from './firestore-checkpointer-CkNKXoun.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';
+import { EventEmitter } from 'events';
+import { Checkpoint } from '@langchain/langgraph-checkpoint';
 export { Command } from '@langchain/langgraph';
 export { D as DomainOrbitalCompleteCallback, a as DomainOrbitalEventCallback, b as DomainOrbitalSpec, c as DomainOrbitalToolOptions, O as OrbitalCompleteCallback, d as OrbitalRequirements, e as OrbitalSubagentToolOptions, S as SubagentEventCallback, f as createConstructCombinedDomainTool, g as createDomainOrbitalTools, h as createGenerateOrbitalDomainTool, i as createOrbitalSubagentTool, j as createSubagentEventWrapper } from './orbital-subagent-cNfTLdXQ.js';
 import 'zod';
 import '@langchain/core/tools';
-import '@langchain/langgraph-checkpoint';
+import '@almadar/core';
+import '@langchain/core/messages';
 import '@langchain/core/runnables';
 
 /**
@@ -365,57 +369,6 @@ declare function isCompleteEvent(event: DeepAgentEvent): event is DeepAgentCompl
  */
 declare function isErrorEvent(event: DeepAgentEvent): event is DeepAgentErrorEvent;
 
-/**
- * Context Compaction for DeepAgent
- *
- * Provides middleware to manage context length in long-running agent sessions.
- * Uses @langchain/core's trimMessages to keep context within token limits.
- *
- * @packageDocumentation
- */
-
-/**
- * Configuration for context compaction.
- */
-interface ContextCompactionConfig {
-    /**
-     * Maximum number of tokens before triggering compaction.
-     * Default: 150000 (leaves headroom for Claude's 200K context)
-     */
-    maxTokens?: number;
-    /**
-     * Number of recent messages to always keep.
-     * Default: 10
-     */
-    keepRecentMessages?: number;
-    /**
-     * Whether to include the system message in trimming.
-     * Default: false (system message is always kept)
-     */
-    includeSystem?: boolean;
-    /**
-     * Strategy for trimming: 'first' keeps first messages, 'last' keeps last messages.
-     * Default: 'last'
-     */
-    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;
-
 /**
  * Metrics Collection for DeepAgent Evaluation
  *
@@ -494,4 +447,703 @@ 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;
+
+/**
+ * Agentic Search - GAP-006
+ *
+ * Reasoning-based search through memory orbitals.
+ * Unlike RAG (vector similarity), this uses agent traversal with understanding
+ * of state transitions, patterns, and temporal relationships.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Search strategy for agentic search
+ */
+type SearchStrategy = 'temporal' | 'semantic' | 'pattern' | 'hybrid';
+/**
+ * Search parameters
+ */
+interface AgenticSearchParams {
+    /** User to search memory for */
+    userId: string;
+    /** Natural language query */
+    query: string;
+    /** Search strategy */
+    strategy?: SearchStrategy;
+    /** Maximum search depth (levels of traversal) */
+    depth?: number;
+    /** App/project context to filter by */
+    appId?: string;
+    /** Maximum results to return */
+    limit?: number;
+}
+/**
+ * Search result with relevance score
+ */
+interface SearchResult {
+    /** Type of memory found */
+    type: 'preference' | 'session' | 'project' | 'interrupt' | 'checkpoint' | 'pattern';
+    /** The actual data */
+    data: unknown;
+    /** Relevance score (0-1) */
+    relevance: number;
+    /** Why this result matched */
+    reasoning: string;
+    /** Source collection */
+    source: string;
+    /** Timestamp for temporal sorting */
+    timestamp?: Date;
+}
+/**
+ * Search result with aggregated insights
+ */
+interface AgenticSearchResponse {
+    /** Individual search results */
+    results: SearchResult[];
+    /** Aggregated insights from results */
+    insights: {
+        /** Summary of what was found */
+        summary: string;
+        /** Common patterns identified */
+        patterns: string[];
+        /** Temporal trends */
+        trends: string[];
+        /** Suggested next actions */
+        suggestions: string[];
+    };
+    /** Search metadata */
+    metadata: {
+        strategy: SearchStrategy;
+        depth: number;
+        duration: number;
+        totalResults: number;
+    };
+}
+declare class AgenticSearchEngine {
+    private memoryManager;
+    constructor(memoryManager: MemoryManager);
+    /**
+     * Perform agentic search through memory
+     */
+    search(params: AgenticSearchParams): Promise<AgenticSearchResponse>;
+    /**
+     * Temporal search - "What did I do last week?"
+     * Navigates memory by time relationships
+     */
+    private temporalSearch;
+    /**
+     * Semantic search - "How did I handle user roles?"
+     * Reasoning-based understanding of structure
+     */
+    private semanticSearch;
+    /**
+     * Pattern search - "Show me all list views I've built"
+     * Searches for specific patterns and effects
+     */
+    private patternSearch;
+    /**
+     * Hybrid search - combines all strategies
+     */
+    private hybridSearch;
+    /**
+     * Extract semantic concepts from query
+     */
+    private extractConcepts;
+    /**
+     * Extract potential entity names from query
+     */
+    private extractEntityNames;
+    /**
+     * Generate insights from search results
+     */
+    private generateInsights;
+}
+/**
+ * Create an agentic search engine
+ */
+declare function createAgenticSearchEngine(memoryManager: MemoryManager): AgenticSearchEngine;
+
+/**
+ * Observability - GAP-008
+ *
+ * Comprehensive observability layer for DeepAgent including:
+ * - Event tracking
+ * - Session metrics
+ * - Performance monitoring
+ * - Health checks
+ *
+ * @packageDocumentation
+ */
+/**
+ * Observable event types
+ */
+type ObservableEventType = 'session_start' | 'session_end' | 'tool_call' | 'tool_result' | 'interrupt' | 'checkpoint_save' | 'checkpoint_restore' | 'error' | 'llm_call' | 'memory_sync';
+/**
+ * Observable event
+ */
+interface ObservableEvent {
+    /** Event type */
+    type: ObservableEventType;
+    /** Timestamp */
+    timestamp: number;
+    /** Session/thread ID */
+    sessionId: string;
+    /** User ID */
+    userId?: string;
+    /** Event payload */
+    payload: Record<string, unknown>;
+    /** Duration in ms (if applicable) */
+    duration?: number;
+    /** Error information */
+    error?: {
+        message: string;
+        code?: string;
+        stack?: string;
+    };
+}
+/**
+ * Session telemetry
+ */
+interface SessionTelemetry {
+    /** Session ID */
+    sessionId: string;
+    /** User ID */
+    userId?: string;
+    /** Session start time */
+    startedAt: number;
+    /** Session end time */
+    endedAt?: number;
+    /** Number of tool calls */
+    toolCallCount: number;
+    /** Number of LLM calls */
+    llmCallCount: number;
+    /** Number of interrupts */
+    interruptCount: number;
+    /** Number of checkpoints */
+    checkpointCount: number;
+    /** Total tokens used */
+    totalTokens: number;
+    /** Errors encountered */
+    errors: Array<{
+        timestamp: number;
+        message: string;
+        type: string;
+    }>;
+    /** Final status */
+    status: 'running' | 'completed' | 'failed' | 'interrupted';
+}
+/**
+ * Performance snapshot
+ */
+interface PerformanceSnapshot {
+    /** Timestamp */
+    timestamp: number;
+    /** Active sessions */
+    activeSessions: number;
+    /** Total sessions (all time) */
+    totalSessions: number;
+    /** Average session duration */
+    avgSessionDuration: number;
+    /** Success rate (last 24h) */
+    successRate24h: number;
+    /** Error rate (last 24h) */
+    errorRate24h: number;
+    /** Average tokens per session */
+    avgTokensPerSession: number;
+}
+/**
+ * Health check result
+ */
+interface HealthCheckResult {
+    /** Component name */
+    component: string;
+    /** Health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Response time in ms */
+    responseTime: number;
+    /** Last checked timestamp */
+    checkedAt: number;
+    /** Error message if unhealthy */
+    error?: string;
+}
+declare class ObservabilityCollector {
+    private events;
+    private sessions;
+    private maxEvents;
+    constructor(options?: {
+        maxEvents?: number;
+    });
+    /**
+     * Record an observable event
+     */
+    recordEvent(event: Omit<ObservableEvent, 'timestamp'>): void;
+    /**
+     * Start session tracking
+     */
+    startSession(sessionId: string, userId?: string): void;
+    /**
+     * End session tracking
+     */
+    endSession(sessionId: string, status?: SessionTelemetry['status']): void;
+    /**
+     * Record tool call
+     */
+    recordToolCall(sessionId: string, toolName: string, args: Record<string, unknown>, duration?: number): void;
+    /**
+     * Record LLM call
+     */
+    recordLLMCall(sessionId: string, model: string, tokens: {
+        input: number;
+        output: number;
+    }, duration?: number): void;
+    /**
+     * Record error
+     */
+    recordError(sessionId: string, error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Get events by type
+     */
+    getEvents(type?: ObservableEventType, sessionId?: string): ObservableEvent[];
+    /**
+     * Get session telemetry
+     */
+    getSessionTelemetry(sessionId: string): SessionTelemetry | undefined;
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions(): SessionTelemetry[];
+    /**
+     * Get performance snapshot
+     */
+    getPerformanceSnapshot(): PerformanceSnapshot;
+    /**
+     * Perform health check
+     */
+    healthCheck(): Promise<HealthCheckResult[]>;
+    /**
+     * Export metrics for external systems
+     */
+    exportMetrics(): {
+        events: ObservableEvent[];
+        sessions: SessionTelemetry[];
+        snapshot: PerformanceSnapshot;
+        health: HealthCheckResult[];
+    };
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    private updateSessionTelemetry;
+}
+/**
+ * Get or create global observability collector
+ */
+declare function getObservabilityCollector(): ObservabilityCollector;
+/**
+ * Reset global observability collector
+ */
+declare function resetObservabilityCollector(): void;
+/**
+ * Record event to global collector
+ */
+declare function recordEvent(event: Omit<ObservableEvent, 'timestamp'>): void;
+/**
+ * Start session in global collector
+ */
+declare function startObservabilitySession(sessionId: string, userId?: string): void;
+/**
+ * End session in global collector
+ */
+declare function endObservabilitySession(sessionId: string, status?: SessionTelemetry['status']): void;
+/**
+ * Get performance snapshot from global collector
+ */
+declare function getPerformanceSnapshot(): PerformanceSnapshot;
+
+/**
+ * Multi-User Support - GAP-009
+ *
+ * Provides proper user isolation and session scoping for multi-user environments.
+ * Ensures users can only access their own sessions, memory, and data.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * User context for multi-user operations
+ */
+interface UserContext {
+    /** User ID */
+    userId: string;
+    /** Organization/tenant ID (for multi-tenant) */
+    orgId?: string;
+    /** User roles/permissions */
+    roles?: string[];
+    /** Session ID scope (optional) */
+    sessionScope?: string[];
+}
+/**
+ * Scoped session metadata with user ownership
+ */
+interface ScopedSessionMetadata extends SessionMetadata {
+    /** Owning user ID */
+    userId: string;
+    /** Organization ID */
+    orgId?: string;
+    /** Created by (for audit) */
+    createdBy: string;
+    /** Last accessed by */
+    lastAccessedBy?: string;
+    /** Access control list */
+    acl?: {
+        /** Users who can read this session */
+        readers?: string[];
+        /** Users who can write/modify */
+        writers?: string[];
+        /** Publicly accessible */
+        isPublic?: boolean;
+    };
+}
+/**
+ * Access check result
+ */
+interface AccessCheckResult {
+    /** Whether access is granted */
+    allowed: boolean;
+    /** Reason if denied */
+    reason?: string;
+    /** Required permission level */
+    requiredRole?: string;
+}
+/**
+ * User session stats
+ */
+interface UserSessionStats {
+    /** User ID */
+    userId: string;
+    /** Total sessions */
+    totalSessions: number;
+    /** Active sessions */
+    activeSessions: number;
+    /** Completed sessions */
+    completedSessions: number;
+    /** Sessions by skill */
+    sessionsBySkill: Record<string, number>;
+    /** Last activity timestamp */
+    lastActivityAt?: number;
+}
+declare class MultiUserManager {
+    private sessionOwnership;
+    private userSessions;
+    /**
+     * Check if a user owns a session
+     */
+    isSessionOwner(threadId: string, userId: string): boolean;
+    /**
+     * Check if a user can access a session
+     */
+    canAccessSession(threadId: string, userContext: UserContext): AccessCheckResult;
+    /**
+     * Assign session ownership
+     */
+    assignSessionOwnership(threadId: string, userId: string): void;
+    /**
+     * Get all sessions for a user
+     */
+    getUserSessions(userId: string): string[];
+    /**
+     * Get session owner
+     */
+    getSessionOwner(threadId: string): string | undefined;
+    /**
+     * Remove session ownership
+     */
+    removeSession(threadId: string): void;
+    /**
+     * Check if user has any sessions
+     */
+    hasSessions(userId: string): boolean;
+    /**
+     * Get user session count
+     */
+    getSessionCount(userId: string): number;
+    /**
+     * Transfer session ownership
+     */
+    transferOwnership(threadId: string, fromUserId: string, toUserId: string): AccessCheckResult;
+    /**
+     * Share session with another user
+     */
+    shareSession(threadId: string, ownerId: string, targetUserId: string, permission?: 'read' | 'write'): AccessCheckResult;
+    /**
+     * Get all user IDs with sessions
+     */
+    getAllUsers(): string[];
+    /**
+     * Clear all data (for testing)
+     */
+    clear(): void;
+    /**
+     * Create scoped session metadata
+     */
+    createScopedMetadata(metadata: SessionMetadata, userContext: UserContext): ScopedSessionMetadata;
+    /**
+     * Validate user context
+     */
+    validateUserContext(userContext: unknown): userContext is UserContext;
+}
+/**
+ * Get or create global multi-user manager
+ */
+declare function getMultiUserManager(): MultiUserManager;
+/**
+ * Reset global multi-user manager
+ */
+declare function resetMultiUserManager(): void;
+/**
+ * Create user context from request
+ */
+declare function createUserContext(userId: string, options?: {
+    orgId?: string;
+    roles?: string[];
+}): UserContext;
+/**
+ * Check if user is admin
+ */
+declare function isAdmin(userContext: UserContext): boolean;
+/**
+ * Require ownership or throw
+ */
+declare function requireOwnership(threadId: string, userContext: UserContext, manager?: MultiUserManager): void;
+
+/**
+ * State Synchronization Support - GAP-010
+ *
+ * Provides agent-side support for real-time state synchronization.
+ * The actual transport (WebSocket/SSE) is handled by @almadar/server.
+ *
+ * This module provides:
+ * - State change notifications
+ * - Conflict resolution utilities
+ * - State serialization for sync
+ * - Event emitters for server integration
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * State change event types
+ */
+type StateChangeType = 'checkpoint_created' | 'checkpoint_updated' | 'session_started' | 'session_ended' | 'tool_executed' | 'memory_updated' | 'interrupt_triggered' | 'interrupt_resolved';
+/**
+ * State change event
+ */
+interface StateChangeEvent {
+    /** Change type */
+    type: StateChangeType;
+    /** Thread/session ID */
+    threadId: string;
+    /** User ID */
+    userId?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Change payload */
+    payload: Record<string, unknown>;
+    /** Version vector for conflict resolution */
+    version: VersionVector;
+    /** Source client ID */
+    sourceClientId?: string;
+}
+/**
+ * Version vector for conflict resolution
+ */
+interface VersionVector {
+    /** Logical timestamp */
+    timestamp: number;
+    /** Sequence number */
+    sequence: number;
+    /** Node/client ID */
+    nodeId: string;
+}
+/**
+ * Sync state snapshot
+ */
+interface StateSyncSnapshot {
+    /** Thread ID */
+    threadId: string;
+    /** Current checkpoint */
+    checkpoint?: Checkpoint;
+    /** Session metadata */
+    sessionMetadata?: Record<string, unknown>;
+    /** Memory state */
+    memoryState?: Record<string, unknown>;
+    /** Version vector */
+    version: VersionVector;
+    /** Last updated */
+    lastUpdated: number;
+}
+/**
+ * Conflict resolution result
+ */
+interface ConflictResolution {
+    /** Whether conflict was resolved */
+    resolved: boolean;
+    /** Winning state if resolved */
+    winningState?: StateSyncSnapshot;
+    /** Conflicting changes if not resolved */
+    conflicts?: Array<{
+        clientA: StateChangeEvent;
+        clientB: StateChangeEvent;
+    }>;
+    /** Resolution strategy used */
+    strategy: 'last_write_wins' | 'merge' | 'manual';
+}
+/**
+ * Sync configuration
+ */
+interface StateSyncConfig {
+    /** Enable sync */
+    enabled: boolean;
+    /** Conflict resolution strategy */
+    conflictStrategy: 'last_write_wins' | 'merge' | 'manual';
+    /** Throttle interval (ms) */
+    throttleInterval: number;
+    /** Max retry attempts */
+    maxRetries: number;
+    /** Client ID */
+    clientId: string;
+}
+declare class StateSyncManager extends EventEmitter {
+    private config;
+    private sequenceNumber;
+    private pendingChanges;
+    private throttleTimer;
+    constructor(config?: Partial<StateSyncConfig>);
+    /**
+     * Notify that state has changed (called by agent internals)
+     */
+    notifyStateChange(type: StateChangeType, threadId: string, payload: Record<string, unknown>, userId?: string): void;
+    /**
+     * Receive state change from server (called by server transport)
+     */
+    receiveRemoteChange(event: StateChangeEvent): void;
+    /**
+     * Create sync snapshot for current state
+     */
+    createSnapshot(threadId: string, state: {
+        checkpoint?: Checkpoint;
+        sessionMetadata?: Record<string, unknown>;
+        memoryState?: Record<string, unknown>;
+    }): StateSyncSnapshot;
+    /**
+     * Compare two version vectors
+     * Returns: -1 if a < b, 0 if concurrent/equal, 1 if a > b
+     */
+    compareVersions(a: VersionVector, b: VersionVector): number;
+    /**
+     * Check if there are pending changes to sync
+     */
+    hasPendingChanges(): boolean;
+    /**
+     * Get and clear pending changes
+     */
+    flushPendingChanges(): StateChangeEvent[];
+    /**
+     * Get sync configuration
+     */
+    getConfig(): StateSyncConfig;
+    /**
+     * Update sync configuration
+     */
+    updateConfig(config: Partial<StateSyncConfig>): void;
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+    private generateClientId;
+    private createVersionVector;
+    private scheduleSync;
+    private findConflicts;
+    private resolveConflicts;
+}
+/**
+ * Get or create global state sync manager
+ */
+declare function getStateSyncManager(config?: Partial<StateSyncConfig>): StateSyncManager;
+/**
+ * Reset global state sync manager
+ */
+declare function resetStateSyncManager(): void;
+/**
+ * Create a synchronized wrapper for session operations
+ */
+declare function withSync<T extends (...args: unknown[]) => unknown>(fn: T, syncManager: StateSyncManager, options: {
+    threadId: string;
+    type: StateChangeType;
+    getPayload: (...args: unknown[]) => Record<string, unknown>;
+}): T;
+/**
+ * Debounce sync notifications
+ */
+declare function debounceSync(syncManager: StateSyncManager, delay?: number): (type: StateChangeType, threadId: string, payload: Record<string, unknown>) => void;
+
+export { type AccessCheckResult, AgenticSearchEngine, type AgenticSearchParams, type AgenticSearchResponse, type ConflictResolution, type DeepAgentCompleteEvent, type DeepAgentErrorEvent, type DeepAgentEvent, type DeepAgentExecutionEvent, type DeepAgentSchemaEvent, type DeepAgentStartEvent, type GenerationMetrics, GenerationSession, type HealthCheckResult, type InferredPreference, MemoryManager, MetricsCollector, type MetricsSummary, MultiUserManager, ObservabilityCollector, type ObservableEvent, type ObservableEventType, type CombinerOptions as OrbitalCombinerOptions, type CombinerResult as OrbitalCombinerResult, type OrbitalSchemaValidationResult, type PerformanceSnapshot, type PreferenceAnalysis, PreferenceLearner, type PreferenceLearnerOptions, type ScopedSessionMetadata, type SearchResult, type SearchStrategy, SessionMetadata, type SessionTelemetry, type StateChangeEvent, type StateChangeType, type StateSyncConfig, StateSyncManager, type StateSyncSnapshot, SubAgent, type UserContext, UserPreference, type UserSessionStats, type VersionVector, analyzeFailures, combineOrbitals, combineOrbitalsToSchema, createAgenticSearchEngine, createErrorFixerSubagent, createPreferenceLearner, createSchemaGeneratorSubagent, createSubagentConfigs, createSubagents, createTestAnalyzerSubagent, createUserContext, debounceSync, endObservabilitySession, estimateCacheSavings, estimateCombineComplexity, formatSummary, generateFullOrbital, getMultiUserManager, getObservabilityCollector, getPerformanceSnapshot, getStateSyncManager, isAdmin, isCompleteEvent, isErrorEvent, isExecutionEvent, isSchemaEvent, isStartEvent, parseDeepAgentEvent, recordEvent, requireOwnership, resetMultiUserManager, resetObservabilityCollector, resetStateSyncManager, startObservabilitySession, withSync };