@sparkleideas/shared 3.0.0-alpha.7

package/src/types/mcp.types.ts

@@ -0,0 +1,300 @@
+/**
+ * V3 MCP Types
+ * Model Context Protocol type definitions
+ * Aligned with ADR-005 (MCP-first API design)
+ */
+
+/**
+ * MCP tool definition
+ */
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: MCPInputSchema;
+  handler: MCPToolHandler;
+}
+
+/**
+ * MCP input schema (JSON Schema)
+ */
+export interface MCPInputSchema {
+  type: 'object';
+  properties: Record<string, MCPPropertySchema>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+/**
+ * MCP property schema
+ */
+export interface MCPPropertySchema {
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  description?: string;
+  enum?: unknown[];
+  default?: unknown;
+  items?: MCPPropertySchema;
+  properties?: Record<string, MCPPropertySchema>;
+  required?: string[];
+}
+
+/**
+ * MCP tool handler
+ */
+export type MCPToolHandler = (params: Record<string, unknown>) => Promise<MCPToolResult>;
+
+/**
+ * MCP tool result
+ */
+export interface MCPToolResult {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+/**
+ * MCP content types
+ */
+export type MCPContent =
+  | MCPTextContent
+  | MCPImageContent
+  | MCPResourceContent;
+
+/**
+ * MCP text content
+ */
+export interface MCPTextContent {
+  type: 'text';
+  text: string;
+}
+
+/**
+ * MCP image content
+ */
+export interface MCPImageContent {
+  type: 'image';
+  data: string;
+  mimeType: string;
+}
+
+/**
+ * MCP resource content
+ */
+export interface MCPResourceContent {
+  type: 'resource';
+  resource: {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+  };
+}
+
+/**
+ * MCP server configuration
+ */
+export interface MCPServerConfig {
+  name: string;
+  version: string;
+  transport: MCPTransportConfig;
+  tools?: MCPTool[];
+  resources?: MCPResource[];
+  prompts?: MCPPrompt[];
+  capabilities?: MCPCapabilities;
+}
+
+/**
+ * MCP transport configuration
+ */
+export interface MCPTransportConfig {
+  type: 'stdio' | 'http' | 'websocket';
+  port?: number;
+  host?: string;
+  path?: string;
+}
+
+/**
+ * MCP resource definition
+ */
+export interface MCPResource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+  handler: () => Promise<MCPResourceContent['resource']>;
+}
+
+/**
+ * MCP prompt definition
+ */
+export interface MCPPrompt {
+  name: string;
+  description?: string;
+  arguments?: MCPPromptArgument[];
+  handler: (args: Record<string, string>) => Promise<MCPPromptResult>;
+}
+
+/**
+ * MCP prompt argument
+ */
+export interface MCPPromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+/**
+ * MCP prompt result
+ */
+export interface MCPPromptResult {
+  messages: MCPPromptMessage[];
+}
+
+/**
+ * MCP prompt message
+ */
+export interface MCPPromptMessage {
+  role: 'user' | 'assistant';
+  content: MCPContent;
+}
+
+/**
+ * MCP capabilities
+ */
+export interface MCPCapabilities {
+  tools?: boolean;
+  resources?: boolean;
+  prompts?: boolean;
+  logging?: boolean;
+  experimental?: Record<string, boolean>;
+}
+
+/**
+ * MCP request types
+ */
+export type MCPRequest =
+  | MCPInitializeRequest
+  | MCPToolCallRequest
+  | MCPResourceReadRequest
+  | MCPPromptGetRequest
+  | MCPListRequest;
+
+/**
+ * MCP initialize request
+ */
+export interface MCPInitializeRequest {
+  method: 'initialize';
+  params: {
+    protocolVersion: string;
+    capabilities: MCPCapabilities;
+    clientInfo: {
+      name: string;
+      version: string;
+    };
+  };
+}
+
+/**
+ * MCP tool call request
+ */
+export interface MCPToolCallRequest {
+  method: 'tools/call';
+  params: {
+    name: string;
+    arguments: Record<string, unknown>;
+  };
+}
+
+/**
+ * MCP resource read request
+ */
+export interface MCPResourceReadRequest {
+  method: 'resources/read';
+  params: {
+    uri: string;
+  };
+}
+
+/**
+ * MCP prompt get request
+ */
+export interface MCPPromptGetRequest {
+  method: 'prompts/get';
+  params: {
+    name: string;
+    arguments?: Record<string, string>;
+  };
+}
+
+/**
+ * MCP list request
+ */
+export interface MCPListRequest {
+  method: 'tools/list' | 'resources/list' | 'prompts/list';
+  params?: Record<string, unknown>;
+}
+
+/**
+ * MCP response types
+ */
+export interface MCPResponse<T = unknown> {
+  id: string | number;
+  result?: T;
+  error?: MCPError;
+}
+
+/**
+ * MCP error
+ */
+export interface MCPError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+/**
+ * MCP event payloads
+ */
+export interface MCPEventPayloads {
+  'mcp:initialized': {
+    serverName: string;
+    version: string;
+    capabilities: MCPCapabilities;
+  };
+  'mcp:tool:called': {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    duration: number;
+    success: boolean;
+  };
+  'mcp:resource:read': {
+    uri: string;
+    mimeType?: string;
+    size: number;
+  };
+  'mcp:prompt:executed': {
+    promptName: string;
+    arguments: Record<string, string>;
+    messageCount: number;
+  };
+  'mcp:error': {
+    error: MCPError;
+    request?: MCPRequest;
+  };
+  'mcp:shutdown': {
+    reason: string;
+  };
+}
+
+/**
+ * MCP server status
+ */
+export interface MCPServerStatus {
+  running: boolean;
+  transport: MCPTransportConfig['type'];
+  connectedClients: number;
+  toolsRegistered: number;
+  resourcesRegistered: number;
+  promptsRegistered: number;
+  requestsHandled: number;
+  errorsCount: number;
+  uptime: number;
+}

package/src/types/memory.types.ts

@@ -0,0 +1,263 @@
+/**
+ * V3 Memory Types
+ * Modernized type system for memory management
+ * Aligned with AgentDB integration (ADR-006, ADR-009)
+ */
+
+import type { IMemoryEntry, MemoryType, IVectorSearchParams, IVectorSearchResult } from '../core/interfaces/memory.interface.js';
+
+/**
+ * Memory backend type
+ */
+export type MemoryBackendType = 'sqlite' | '@sparkleideas/agentdb' | 'hybrid' | 'redis' | 'memory';
+
+/**
+ * Memory backend configuration
+ */
+export interface MemoryBackendConfig {
+  type: MemoryBackendType;
+  path?: string;
+  maxSize?: number;
+  ttlMs?: number;
+
+  // SQLite specific
+  sqlite?: {
+    filename?: string;
+    inMemory?: boolean;
+    wal?: boolean;
+  };
+
+  // AgentDB specific (vector storage)
+  @sparkleideas/agentdb?: {
+    dimensions?: number;
+    indexType?: 'hnsw' | 'flat' | 'ivf';
+    efConstruction?: number;
+    m?: number;
+    quantization?: 'none' | 'scalar' | 'product';
+  };
+
+  // Redis specific
+  redis?: {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    keyPrefix?: string;
+  };
+
+  // Hybrid (SQLite + AgentDB)
+  hybrid?: {
+    sqliteConfig?: MemoryBackendConfig['sqlite'];
+    agentdbConfig?: MemoryBackendConfig['@sparkleideas/agentdb'];
+    vectorThreshold?: number;
+  };
+}
+
+/**
+ * Memory store options
+ */
+export interface MemoryStoreOptions {
+  ttlMs?: number;
+  type?: MemoryType;
+  tags?: string[];
+  embedding?: number[];
+  overwrite?: boolean;
+}
+
+/**
+ * Memory retrieve options
+ */
+export interface MemoryRetrieveOptions {
+  includeExpired?: boolean;
+  updateAccessTime?: boolean;
+}
+
+/**
+ * Memory list options
+ */
+export interface MemoryListOptions {
+  type?: MemoryType;
+  tags?: string[];
+  limit?: number;
+  offset?: number;
+  sortBy?: 'createdAt' | 'updatedAt' | 'key';
+  sortOrder?: 'asc' | 'desc';
+}
+
+/**
+ * Memory search options (for vector search)
+ */
+export interface MemorySearchOptions extends IVectorSearchParams {
+  includeMetadata?: boolean;
+  rerank?: boolean;
+  rerankModel?: string;
+}
+
+/**
+ * Memory batch operation
+ */
+export interface MemoryBatchOperation {
+  operation: 'store' | 'update' | 'delete';
+  key: string;
+  value?: unknown;
+  options?: MemoryStoreOptions;
+}
+
+/**
+ * Memory batch result
+ */
+export interface MemoryBatchResult {
+  successful: string[];
+  failed: Array<{ key: string; error: Error }>;
+  duration: number;
+}
+
+/**
+ * Memory statistics
+ */
+export interface MemoryStats {
+  totalEntries: number;
+  totalSizeBytes: number;
+  memoryUsageMb: number;
+  entriesByType: Record<MemoryType, number>;
+  oldestEntry?: Date;
+  newestEntry?: Date;
+  avgEntrySize: number;
+  cacheHitRate?: number;
+  vectorCount?: number;
+  indexSize?: number;
+}
+
+/**
+ * Memory bank statistics
+ */
+export interface MemoryBankStats {
+  bankId: string;
+  agentId: string;
+  entryCount: number;
+  sizeMb: number;
+  createdAt: Date;
+  lastAccess: Date;
+}
+
+/**
+ * Pattern for ReasoningBank integration
+ */
+export interface LearnedPattern {
+  id: string;
+  sessionId: string;
+  task: string;
+  input: string;
+  output: string;
+  reward: number;
+  success: boolean;
+  critique?: string;
+  tokensUsed?: number;
+  latencyMs?: number;
+  createdAt: Date;
+  embedding?: number[];
+}
+
+/**
+ * Pattern search result
+ */
+export interface PatternSearchResult {
+  pattern: LearnedPattern;
+  score: number;
+  relevance: number;
+}
+
+/**
+ * Memory event payloads
+ */
+export interface MemoryEventPayloads {
+  'memory:stored': {
+    entry: IMemoryEntry;
+    isNew: boolean;
+  };
+  'memory:retrieved': {
+    key: string;
+    found: boolean;
+    latencyMs: number;
+  };
+  'memory:updated': {
+    entry: IMemoryEntry;
+    previousValue: unknown;
+  };
+  'memory:deleted': {
+    key: string;
+    entry: IMemoryEntry;
+  };
+  'memory:cleared': {
+    entriesRemoved: number;
+  };
+  'memory:pruned': {
+    entriesRemoved: number;
+    durationMs: number;
+  };
+  'memory:search:completed': {
+    query: IVectorSearchParams;
+    resultCount: number;
+    latencyMs: number;
+  };
+  'memory:bank:created': {
+    bankId: string;
+    agentId: string;
+  };
+  'memory:bank:closed': {
+    bankId: string;
+    agentId: string;
+    entriesCount: number;
+  };
+}
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+  enabled: boolean;
+  maxSize: number;
+  ttlMs: number;
+  strategy: 'lru' | 'lfu' | 'fifo';
+  warmupKeys?: string[];
+}
+
+/**
+ * Vector index configuration
+ */
+export interface VectorIndexConfig {
+  type: 'hnsw' | 'flat' | 'ivf';
+  dimensions: number;
+  metric: 'cosine' | 'euclidean' | 'dot';
+
+  // HNSW specific (150x faster search)
+  hnsw?: {
+    m: number;
+    efConstruction: number;
+    efSearch: number;
+  };
+
+  // IVF specific
+  ivf?: {
+    nlist: number;
+    nprobe: number;
+  };
+
+  // Quantization (4-32x memory reduction)
+  quantization?: {
+    enabled: boolean;
+    bits: 4 | 8 | 16;
+    type: 'scalar' | 'product';
+  };
+}
+
+/**
+ * Flash Attention configuration (2.49x-7.47x speedup)
+ */
+export interface FlashAttentionConfig {
+  enabled: boolean;
+  blockSize: number;
+  headDim: number;
+  causal: boolean;
+  softmaxScale?: number;
+}