@mxf-dev/core 1.0.0

package/src/types/McpPromptTypes.ts

@@ -0,0 +1,299 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * MCP Prompts Type Definitions
+ *
+ * Type definitions for the Model Context Protocol (MCP) Prompts feature.
+ * Prompts provide server-defined prompt templates that clients can discover
+ * and invoke with arguments for dynamic agent configuration and task decomposition.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/server/prompts
+ */
+
+/**
+ * Argument definition for a prompt
+ */
+export interface PromptArgument {
+    /** Argument name */
+    name: string;
+    /** Human-readable description of the argument */
+    description?: string;
+    /** Whether this argument is required */
+    required?: boolean;
+    /** Default value for the argument (MXF extension) */
+    defaultValue?: unknown;
+}
+
+/**
+ * Prompt definition metadata
+ */
+export interface PromptDefinition {
+    /** Unique identifier for the prompt */
+    name: string;
+    /** Human-readable title */
+    title?: string;
+    /** Description of the prompt's purpose */
+    description?: string;
+    /** List of argument definitions */
+    arguments?: PromptArgument[];
+    /** Source MCP server ID (MXF extension) */
+    serverId: string;
+}
+
+/**
+ * Text content in a prompt message
+ */
+export interface PromptTextContent {
+    type: 'text';
+    text: string;
+}
+
+/**
+ * Image content in a prompt message
+ */
+export interface PromptImageContent {
+    type: 'image';
+    /** Base64-encoded image data */
+    data: string;
+    /** MIME type of the image */
+    mimeType: string;
+}
+
+/**
+ * Audio content in a prompt message
+ */
+export interface PromptAudioContent {
+    type: 'audio';
+    /** Base64-encoded audio data */
+    data: string;
+    /** MIME type of the audio */
+    mimeType: string;
+}
+
+/**
+ * Embedded resource in a prompt message
+ */
+export interface EmbeddedResource {
+    /** Resource URI (e.g., resource://server/path) */
+    uri: string;
+    /** MIME type of the resource */
+    mimeType?: string;
+    /** Text content if available */
+    text?: string;
+    /** Base64-encoded binary content if available */
+    blob?: string;
+}
+
+/**
+ * Resource content in a prompt message
+ */
+export interface PromptResourceContent {
+    type: 'resource';
+    resource: EmbeddedResource;
+}
+
+/**
+ * Union type for all prompt content types
+ */
+export type PromptContent =
+    | PromptTextContent
+    | PromptImageContent
+    | PromptAudioContent
+    | PromptResourceContent;
+
+/**
+ * Message in a resolved prompt
+ */
+export interface PromptMessage {
+    /** Message role */
+    role: 'user' | 'assistant';
+    /** Message content (can be single or array) */
+    content: PromptContent | PromptContent[];
+}
+
+/**
+ * Metadata for a resolved prompt
+ */
+export interface PromptMetadata {
+    /** Timestamp when the prompt was resolved */
+    resolvedAt: Date;
+    /** Source MCP server ID */
+    serverId: string;
+    /** Estimated token count for MXP integration */
+    tokenEstimate: number;
+    /** Arguments used for resolution */
+    argumentsUsed: Record<string, unknown>;
+}
+
+/**
+ * Fully resolved prompt with messages
+ */
+export interface ResolvedPrompt {
+    /** Optional description of the prompt */
+    description?: string;
+    /** Array of messages in the prompt */
+    messages: PromptMessage[];
+    /** Metadata about the resolution */
+    metadata: PromptMetadata;
+}
+
+/**
+ * MCP Protocol: prompts/list request
+ */
+export interface PromptsListRequest {
+    /** Cursor for pagination (null for first page) */
+    cursor?: string | null;
+}
+
+/**
+ * MCP Protocol: prompts/list response
+ */
+export interface PromptsListResponse {
+    /** Array of available prompts */
+    prompts: PromptDefinition[];
+    /** Cursor for next page, or undefined if no more pages */
+    nextCursor?: string;
+}
+
+/**
+ * MCP Protocol: prompts/get request
+ */
+export interface PromptsGetRequest {
+    /** Name of the prompt to retrieve */
+    name: string;
+    /** Argument values for prompt resolution */
+    arguments?: Record<string, unknown>;
+}
+
+/**
+ * MCP Protocol: prompts/get response
+ */
+export interface PromptsGetResponse {
+    /** Optional description */
+    description?: string;
+    /** Array of messages in the prompt */
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: PromptContent | PromptContent[];
+    }>;
+}
+
+/**
+ * Cache statistics for the prompts manager
+ */
+export interface PromptCacheStats {
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Current number of cached entries */
+    size: number;
+    /** Maximum cache capacity */
+    maxSize: number;
+    /** Cache hit rate (0.0 to 1.0) */
+    hitRate: number;
+}
+
+/**
+ * Configuration for MCP Prompts integration
+ */
+export interface MxfPromptsConfig {
+    /** Whether prompts feature is enabled */
+    enabled: boolean;
+    /** Cache configuration */
+    cache: {
+        /** Cache strategy: memory, redis, or none */
+        strategy: 'memory' | 'redis' | 'none';
+        /** Time-to-live in seconds */
+        ttlSeconds: number;
+        /** Maximum number of cached entries */
+        maxEntries: number;
+    };
+    /** Discovery configuration */
+    discovery: {
+        /** Refresh interval in seconds */
+        refreshIntervalSeconds: number;
+        /** Discovery timeout in milliseconds */
+        timeoutMs: number;
+    };
+    /** Resolution configuration */
+    resolution: {
+        /** Maximum embedded resource size in bytes */
+        maxEmbeddedResourceSize: number;
+        /** Allowed resource URI schemes */
+        allowedResourceSchemes: string[];
+    };
+    /** MXP integration configuration */
+    mxpIntegration: {
+        /** Whether to compress embedded resources */
+        compressEmbeddedResources: boolean;
+        /** Whether to track token usage */
+        trackTokenUsage: boolean;
+    };
+}
+
+/**
+ * Source for prompt argument resolution
+ */
+export enum ArgumentResolutionSource {
+    /** Explicitly provided by caller */
+    EXPLICIT = 'explicit',
+    /** Resolved from task context */
+    TASK_CONTEXT = 'task_context',
+    /** Resolved from agent context */
+    AGENT_CONTEXT = 'agent_context',
+    /** Resolved from channel context */
+    CHANNEL_CONTEXT = 'channel_context',
+    /** Inferred by SystemLLM */
+    SYSTEM_LLM = 'system_llm',
+    /** Default value from prompt definition */
+    DEFAULT = 'default'
+}
+
+/**
+ * Result of argument resolution
+ */
+export interface ArgumentResolutionResult {
+    /** Resolved value */
+    value: unknown;
+    /** Where the value came from */
+    source: ArgumentResolutionSource;
+    /** Confidence score (0.0 to 1.0) for inferred values */
+    confidence?: number;
+}
+
+/**
+ * Context for prompt argument resolution
+ */
+export interface PromptResolutionContext {
+    /** Agent ID requesting the prompt */
+    agentId?: string;
+    /** Channel ID for context */
+    channelId?: string;
+    /** Task context */
+    taskContext?: Record<string, unknown>;
+    /** Agent context */
+    agentContext?: Record<string, unknown>;
+    /** Channel context */
+    channelContext?: Record<string, unknown>;
+    /** Explicitly provided arguments */
+    explicitArgs?: Record<string, unknown>;
+}

package/src/types/MemoryStrataTypes.ts

@@ -0,0 +1,378 @@
+/**
+ * Memory Strata Types for MXF
+ *
+ * Type definitions for multi-layered memory architecture with surprise detection.
+ * Feature flag: MEMORY_STRATA_ENABLED
+ */
+
+/**
+ * Memory layer/stratum level
+ */
+export enum MemoryStratum {
+  /** Working memory (immediate context) */
+  Working = 'working',
+  /** Short-term memory (recent history) */
+  ShortTerm = 'short_term',
+  /** Long-term memory (persistent knowledge) */
+  LongTerm = 'long_term',
+  /** Episodic memory (specific events) */
+  Episodic = 'episodic',
+  /** Semantic memory (facts and concepts) */
+  Semantic = 'semantic',
+}
+
+/**
+ * Memory importance level
+ */
+export enum MemoryImportance {
+  Critical = 5,
+  High = 4,
+  Medium = 3,
+  Low = 2,
+  Trivial = 1,
+}
+
+/**
+ * Memory entry
+ */
+export interface MemoryEntry {
+  /** Unique entry ID */
+  id: string;
+  /** Memory stratum */
+  stratum: MemoryStratum;
+  /** Entry content */
+  content: string;
+  /** Content type */
+  contentType: 'text' | 'structured' | 'embedding';
+  /** Structured data (if contentType is structured) */
+  structuredData?: Record<string, unknown>;
+  /** Embedding vector (if contentType is embedding) */
+  embedding?: number[];
+  /** Importance level */
+  importance: MemoryImportance;
+  /** Related tags */
+  tags: string[];
+  /** Source of memory */
+  source: MemorySource;
+  /** Context when memory was created */
+  context: MemoryContext;
+  /** Access count */
+  accessCount: number;
+  /** Last accessed timestamp */
+  lastAccessed: Date;
+  /** Created timestamp */
+  createdAt: Date;
+  /** Expiration timestamp (optional) */
+  expiresAt?: Date;
+  /** Links to related memories */
+  relatedMemories: string[];
+  /** Metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Memory source
+ */
+export interface MemorySource {
+  /** Source type */
+  type: 'conversation' | 'observation' | 'reasoning' | 'reflection' | 'learning' | 'external';
+  /** Source agent ID */
+  agentId?: string;
+  /** Source channel ID */
+  channelId?: string;
+  /** Source event ID */
+  eventId?: string;
+  /** Additional source data */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Memory context
+ */
+export interface MemoryContext {
+  /** Agent ID */
+  agentId: string;
+  /** Channel ID */
+  channelId?: string;
+  /** Task ID */
+  taskId?: string;
+  /** ORPAR phase */
+  orparPhase?: 'observe' | 'reason' | 'plan' | 'act' | 'reflect';
+  /** Timestamp */
+  timestamp: Date;
+  /** Additional context data */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Surprise detection result
+ */
+export interface SurpriseDetection {
+  /** Is this surprising? */
+  isSurprising: boolean;
+  /** Surprise score (0-1) */
+  surpriseScore: number;
+  /** Surprise type */
+  type?: SurpriseType;
+  /** Explanation of why it's surprising */
+  explanation?: string;
+  /** Expectation that was violated */
+  expectation?: MemoryExpectation;
+  /** Actual observation */
+  observation: string;
+  /** Suggested actions */
+  suggestedActions?: string[];
+}
+
+/**
+ * Surprise type
+ */
+export type SurpriseType =
+  | 'schema_violation'      // Violates known schema/pattern
+  | 'prediction_failure'    // Prediction was wrong
+  | 'anomaly'              // Statistical anomaly
+  | 'novel_pattern'        // New pattern detected
+  | 'context_mismatch'     // Context doesn't match expectations
+  | 'performance_deviation' // Performance differs from baseline
+  | 'unexpected_error'     // Unexpected error occurred
+  | 'unexpected_success';  // Unexpected success occurred
+
+/**
+ * Memory expectation
+ */
+export interface MemoryExpectation {
+  /** Expected value or pattern */
+  expected: unknown;
+  /** Confidence in expectation (0-1) */
+  confidence: number;
+  /** Source of expectation */
+  source: 'pattern' | 'rule' | 'learning' | 'prior';
+  /** Related memory IDs */
+  basedOn: string[];
+}
+
+/**
+ * Memory consolidation result
+ */
+export interface MemoryConsolidation {
+  /** Memories consolidated */
+  consolidatedMemories: string[];
+  /** New consolidated memory */
+  newMemory: MemoryEntry;
+  /** Consolidation type */
+  type: ConsolidationType;
+  /** Consolidation reason */
+  reason: string;
+}
+
+/**
+ * Consolidation type
+ */
+export type ConsolidationType =
+  | 'merge'           // Merge similar memories
+  | 'summarize'       // Summarize multiple memories
+  | 'abstract'        // Abstract common pattern
+  | 'promote'         // Promote to higher stratum
+  | 'demote'          // Demote to lower stratum
+  | 'archive';        // Archive old memories
+
+/**
+ * Memory retrieval query
+ */
+export interface MemoryQuery {
+  /** Query text */
+  query: string;
+  /** Strata to search */
+  strata?: MemoryStratum[];
+  /** Minimum importance */
+  minImportance?: MemoryImportance;
+  /** Tags filter */
+  tags?: string[];
+  /** Context filter */
+  context?: Partial<MemoryContext>;
+  /** Time range filter */
+  timeRange?: {
+    start?: Date;
+    end?: Date;
+  };
+  /** Maximum results */
+  limit?: number;
+  /** Include embeddings in results */
+  includeEmbeddings?: boolean;
+}
+
+/**
+ * Memory retrieval result
+ */
+export interface MemoryRetrievalResult {
+  /** Retrieved memories */
+  memories: MemoryEntry[];
+  /** Total count (before limit) */
+  totalCount: number;
+  /** Retrieval scores (memory ID -> score) */
+  scores: Map<string, number>;
+  /** Query execution time (milliseconds) */
+  executionTime: number;
+}
+
+/**
+ * Memory pattern
+ */
+export interface MemoryPattern {
+  /** Pattern ID */
+  id: string;
+  /** Pattern name */
+  name: string;
+  /** Pattern description */
+  description?: string;
+  /** Pattern type */
+  type: 'sequential' | 'causal' | 'correlational' | 'structural';
+  /** Pattern elements */
+  elements: MemoryPatternElement[];
+  /** Pattern confidence (0-1) */
+  confidence: number;
+  /** Supporting evidence (memory IDs) */
+  evidence: string[];
+  /** Times observed */
+  observationCount: number;
+  /** Last observed */
+  lastObserved: Date;
+  /** Created timestamp */
+  createdAt: Date;
+}
+
+/**
+ * Memory pattern element
+ */
+export interface MemoryPatternElement {
+  /** Element position in pattern */
+  position: number;
+  /** Element description */
+  description: string;
+  /** Element constraints */
+  constraints?: Record<string, unknown>;
+  /** Temporal relation to previous element */
+  temporalRelation?: 'before' | 'after' | 'during' | 'concurrent';
+}
+
+/**
+ * Memory strata configuration
+ */
+export interface MemoryStrataConfig {
+  /** Enable memory strata system */
+  enabled: boolean;
+
+  /** Working memory configuration */
+  working: {
+    /** Maximum entries */
+    maxEntries: number;
+    /** Time-to-live (milliseconds) */
+    ttl: number;
+  };
+
+  /** Short-term memory configuration */
+  shortTerm: {
+    /** Maximum entries */
+    maxEntries: number;
+    /** Time-to-live (milliseconds) */
+    ttl: number;
+    /** Consolidation threshold */
+    consolidationThreshold: number;
+  };
+
+  /** Long-term memory configuration */
+  longTerm: {
+    /** Maximum entries per agent */
+    maxEntriesPerAgent: number;
+    /** Minimum importance for storage */
+    minImportance: MemoryImportance;
+    /** Enable automatic archival */
+    enableArchival: boolean;
+    /** Archival age threshold (milliseconds) */
+    archivalAge: number;
+  };
+
+  /** Episodic memory configuration */
+  episodic: {
+    /** Maximum episodes per agent */
+    maxEpisodesPerAgent: number;
+    /** Episode duration threshold (milliseconds) */
+    episodeDuration: number;
+  };
+
+  /** Semantic memory configuration */
+  semantic: {
+    /** Maximum concepts per agent */
+    maxConceptsPerAgent: number;
+    /** Minimum confidence for storage */
+    minConfidence: number;
+  };
+
+  /** Surprise detection */
+  surprise: {
+    /** Enable surprise detection */
+    enabled: boolean;
+    /** Surprise threshold (0-1) */
+    threshold: number;
+    /** Analysis window (number of recent memories) */
+    analysisWindow: number;
+  };
+
+  /** Consolidation */
+  consolidation: {
+    /** Enable automatic consolidation */
+    enabled: boolean;
+    /** Consolidation interval (milliseconds) */
+    interval: number;
+    /** Similarity threshold for merging */
+    similarityThreshold: number;
+  };
+
+  /** Pattern detection */
+  patterns: {
+    /** Enable pattern detection */
+    enabled: boolean;
+    /** Minimum pattern length */
+    minLength: number;
+    /** Minimum confidence */
+    minConfidence: number;
+    /** Analysis interval (milliseconds) */
+    analysisInterval: number;
+  };
+}
+
+/**
+ * Memory statistics
+ */
+export interface MemoryStatistics {
+  /** Total entries per stratum */
+  entriesPerStratum: Record<MemoryStratum, number>;
+  /** Total entries per importance */
+  entriesPerImportance: Record<MemoryImportance, number>;
+  /** Average access count */
+  avgAccessCount: number;
+  /** Most accessed memories */
+  mostAccessed: string[];
+  /** Recent surprises */
+  recentSurprises: number;
+  /** Detected patterns */
+  detectedPatterns: number;
+  /** Memory usage (bytes) */
+  memoryUsage: number;
+}
+
+/**
+ * Memory transition event
+ */
+export interface MemoryTransition {
+  /** Memory ID */
+  memoryId: string;
+  /** Source stratum */
+  fromStratum: MemoryStratum;
+  /** Destination stratum */
+  toStratum: MemoryStratum;
+  /** Transition reason */
+  reason: string;
+  /** Transition timestamp */
+  timestamp: Date;
+}