@pikku/core 0.7.8 → 0.8.0

package/src/events/mcp/mcp.types.ts

@@ -0,0 +1,150 @@
+import { CoreAPIFunctionSessionless } from '../../function/functions.types.js'
+
+export type PikkuMCP<Tools extends string = any> = {
+  // elicitInput: <Input>(message: string) => Promise<{ action: string, content: Input }>
+  uri?: string
+  sendResourceUpdated: (uri: string) => void
+  enableResources: (resources: Record<string, boolean>) => Promise<boolean>
+  enablePrompts: (prompts: Record<string, boolean>) => Promise<boolean>
+  enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>
+}
+
+/**
+ * Represents metadata for MCP resources, including name, description, and documentation.
+ */
+export type MCPResourceMeta = Record<
+  string,
+  Omit<CoreMCPResource, 'func'> & {
+    pikkuFuncName: string
+    inputSchema: string | null
+    outputSchema: string | null
+  }
+>
+
+/**
+ * Represents metadata for MCP tools, including name, description, and documentation.
+ */
+export type MCPToolMeta = Record<
+  string,
+  Omit<CoreMCPTool, 'func'> & {
+    pikkuFuncName: string
+    inputSchema: string | null
+    outputSchema: string | null
+  }
+>
+
+/**
+ * Represents metadata for MCP prompts, including name, description, and arguments.
+ */
+export type MCPPromptMeta = Record<
+  string,
+  Omit<CoreMCPPrompt, 'func'> & {
+    pikkuFuncName: string
+    inputSchema: string | null
+    outputSchema: string | null
+    arguments: Array<{
+      name: string
+      description: string
+      required: boolean
+    }>
+  }
+>
+
+/**
+ * Represents an MCP resource with specific properties.
+ */
+export type CoreMCPResource<
+  APIFunction = CoreAPIFunctionSessionless<any, any>,
+> = {
+  uri: string
+  title: string
+  description?: string
+  mimeType?: string
+  size?: number
+  streaming?: boolean
+  func: APIFunction
+  tags?: string[]
+}
+
+/**
+ * Represents an MCP tool with specific properties.
+ */
+export type CoreMCPTool<APIFunction = CoreAPIFunctionSessionless<any, any>> = {
+  name: string
+  title?: string
+  description: string
+  annotations?: Record<string, any>
+  func: APIFunction
+  tags?: string[]
+  streaming?: boolean
+}
+
+/**
+ * Represents an MCP prompt with specific properties.
+ */
+export type CoreMCPPrompt<
+  APIFunction = CoreAPIFunctionSessionless<any, MCPPromptResponse>,
+> = {
+  name: string
+  description?: string
+  func: APIFunction
+  tags?: string[]
+}
+
+export type JsonRpcRequest = {
+  jsonrpc: string
+  id?: string | number | null
+  params?: any
+}
+
+export type JsonRpcResponse = {
+  id?: string | number | null
+  result?: any
+}
+
+export type JsonRpcErrorResponse = {
+  id?: string | number | null
+  code: number
+  message: string
+  data?: any
+}
+
+/**
+ * Represents a message in an MCP prompt response
+ */
+export type MCPPromptMessage = {
+  role: 'user' | 'assistant' | 'system'
+  content: {
+    type: 'text' | 'image'
+    text: string
+    data?: string // for image content
+  }
+}
+
+/**
+ * Standard response type for MCP prompts - array of messages
+ */
+export type MCPPromptResponse = MCPPromptMessage[]
+
+export type MCPResourceMessage = {
+  uri: string
+  text: string
+}
+
+export type MCPResourceResponse = MCPResourceMessage[]
+
+/**
+ * Standard response type for MCP prompts - array of messages
+ */
+
+export type MCPToolMessage =
+  | {
+      type: 'text'
+      text: string
+    }
+  | {
+      type: 'image'
+      data: string // base64 encoded image data
+    }
+
+export type MCPToolResponse = MCPToolMessage[]

package/src/events/queue/index.ts

@@ -0,0 +1,18 @@
+// Queue types
+export type * from './queue.types.js'
+
+// Queue processor management
+export {
+  addQueueWorker,
+  runQueueJob,
+  getQueueWorkers,
+  removeQueueWorker,
+} from './queue-runner.js'
+
+// Configuration validation
+export { validateWorkerConfig } from './validate-worker-config.js'
+export type { QueueConfigMapping } from './validate-worker-config.js'
+
+// Queue registration helper
+export { registerqueueWorkers } from './register-queue-helper.js'
+export type { QueueRegistrationCallback } from './register-queue-helper.js'

package/src/events/queue/queue-runner.ts

@@ -0,0 +1,125 @@
+import type { CoreServices } from '../../types/core.types.js'
+import type { CoreQueueWorker, QueueJob } from './queue.types.js'
+import type { CoreAPIFunctionSessionless } from '../../function/functions.types.js'
+import { getErrorResponse } from '../../errors/error-handler.js'
+import { pikkuState } from '../../pikku-state.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { CreateSessionServices } from '../../types/core.types.js'
+
+/**
+ * Error class for queue processor not found
+ */
+class QueueWorkerNotFoundError extends Error {
+  constructor(name: string) {
+    super(`Queue processor not found: ${name}`)
+  }
+}
+/**
+ * Add a queue processor to the system
+ */
+export const addQueueWorker = <
+  InputData = any,
+  OutputData = any,
+  APIFunction extends CoreAPIFunctionSessionless<
+    InputData,
+    OutputData
+  > = CoreAPIFunctionSessionless<InputData, OutputData>,
+>(
+  queueWorker: CoreQueueWorker<APIFunction>
+) => {
+  // Get processor metadata
+  const meta = pikkuState('queue', 'meta')
+  const processorMeta = meta[queueWorker.queueName]
+  if (!processorMeta) {
+    throw new Error(
+      `Queue processor metadata not found for '${queueWorker.queueName}'. Make sure to run the CLI to generate metadata.`
+    )
+  }
+
+  // Register the function with pikku
+  addFunction(processorMeta.pikkuFuncName, {
+    func: queueWorker.func,
+  })
+
+  // Store processor definition in state - runtime adapters will pick this up
+  const registrations = pikkuState('queue', 'registrations')
+  registrations.set(queueWorker.queueName, queueWorker)
+}
+
+/**
+ * Get all registered queue processors
+ */
+export function getQueueWorkers(): Map<string, CoreQueueWorker> {
+  return pikkuState('queue', 'registrations')
+}
+
+/**
+ * Stop and remove a queue processor
+ */
+export async function removeQueueWorker(name: string): Promise<void> {
+  const registrations = pikkuState('queue', 'registrations')
+  const registration = registrations.get(name)
+
+  if (!registration) {
+    throw new QueueWorkerNotFoundError(name)
+  }
+
+  registrations.delete(name)
+}
+
+/**
+ * Process a single queue job - this function is called by queue consumers
+ */
+export async function runQueueJob({
+  singletonServices,
+  createSessionServices,
+  job,
+}: {
+  singletonServices: CoreServices
+  createSessionServices?: CreateSessionServices
+  job: QueueJob
+}): Promise<void> {
+  const logger = singletonServices.logger
+
+  const meta = pikkuState('queue', 'meta')
+  const processorMeta = meta[job.queueName]
+  if (!processorMeta) {
+    throw new Error(`Processor metadata not found for: ${job.queueName}`)
+  }
+
+  try {
+    logger.info(`Processing job ${job.id} in queue ${job.queueName}`)
+
+    // Use provided singleton services
+    const getAllServices = () => ({
+      ...singletonServices,
+      ...(createSessionServices
+        ? createSessionServices(singletonServices, {}, undefined)
+        : {}),
+    })
+
+    // Execute the pikku function with the job data
+    const result = await runPikkuFunc(processorMeta.pikkuFuncName, {
+      getAllServices,
+      data: job.data,
+    })
+
+    logger.debug(
+      `Successfully processed job ${job.id} in queue ${job.queueName}`
+    )
+    return result
+  } catch (error: any) {
+    logger.error(
+      `Error processing job ${job.id} in queue ${job.queueName}:`,
+      error
+    )
+
+    const errorResponse = getErrorResponse(error)
+    if (errorResponse != null) {
+      logger.error('Processed error response:', errorResponse)
+    }
+
+    // Re-throw the error so the queue service can handle retries/DLQ
+    throw error
+  }
+}

package/src/events/queue/queue.types.ts

@@ -0,0 +1,176 @@
+import { APIDocs } from '../../types/core.types.js'
+import { CoreAPIFunctionSessionless } from '../../function/functions.types.js'
+import { QueueConfigMapping } from './validate-worker-config.js'
+
+/**
+ * Configuration for queue workers - how jobs are processed
+ */
+/**
+ * Configuration for queue workers - how jobs are processed
+ */
+export interface PikkuWorkerConfig {
+  /** Optional worker name for identification and monitoring */
+  name?: string
+  /** Number of messages to process in batch / in parallel */
+  batchSize?: number
+  /** Number of messages to prefetch for efficiency */
+  prefetch?: number
+  /** Polling interval for pull-based queues in ms */
+  pollInterval?: number
+  /** Message visibility timeout in seconds */
+  visibilityTimeout?: number
+  /** Duration of job lock in milliseconds */
+  lockDuration?: number
+  /** Number of seconds to wait when queue is empty before polling again */
+  drainDelay?: number
+  /** Keep N completed jobs for inspection */
+  removeOnComplete?: number
+  /** Keep N failed jobs for inspection */
+  removeOnFail?: number
+  /** Maximum number of times a job can be recovered from stalled state */
+  maxStalledCount?: number
+  /** Condition to start processor at instance creation */
+  autorun?: boolean
+}
+
+/**
+ * Configuration for individual jobs - how jobs behave
+ */
+export interface PikkuJobConfig {
+  /** Maximum retry attempts for failed jobs */
+  retryAttempts?: number
+  /** Initial retry delay in milliseconds */
+  retryDelay?: number
+  /** Retry backoff strategy */
+  retryBackoff?: 'linear' | 'exponential' | 'fixed'
+  /** Queue for failed messages after max retries */
+  deadLetterQueue?: string
+  /** How long to retain completed jobs in seconds */
+  messageRetention?: number
+  /** Job priority (higher numbers = higher priority) */
+  priority?: number
+  /** Enable FIFO ordering where supported */
+  fifo?: boolean
+  /** Job timeout in milliseconds */
+  timeout?: number
+  /** Delay before job execution in milliseconds */
+  delay?: number
+}
+
+/**
+ * Configuration validation result with warnings and fallbacks
+ */
+export interface ConfigValidationResult {
+  applied: Partial<PikkuWorkerConfig>
+  ignored: Partial<PikkuWorkerConfig>
+  warnings: string[]
+  fallbacks: { [key: string]: any }
+}
+
+/**
+ * Queue job representation
+ */
+export type QueueJobStatus =
+  | 'waiting'
+  | 'active'
+  | 'completed'
+  | 'failed'
+  | 'delayed'
+
+export type QueueJobMetadata = {
+  progress?: number | string | object | undefined | boolean
+  attemptsMade?: number
+  maxAttempts?: number
+  processedAt?: Date
+  completedAt?: Date
+  failedAt?: Date
+  error?: string
+  createdAt: Date
+}
+
+export interface QueueJob<T = any, R = any> {
+  id: string
+  queueName: string
+  status: () => Promise<QueueJobStatus> | QueueJobStatus
+  data: T
+  result?: R
+  waitForCompletion?: (ttl?: number) => Promise<R>
+  metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata
+}
+
+/**
+ * Job options for queue operations
+ */
+export interface JobOptions {
+  priority?: number
+  delay?: number
+  attempts?: number
+  backoff?: string | { type: string; delay?: number }
+  removeOnComplete?: number
+  removeOnFail?: number
+  jobId?: string
+}
+
+/**
+ * Queue provider interface for job publishing operations
+ */
+export interface QueueService {
+  /** Whether this queue provider supports job results */
+  readonly supportsResults: boolean
+
+  /** Add a job to the queue with type safety */
+  add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>
+
+  /** Get job status and result */
+  getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>
+}
+
+/**
+ * Queue service interface that queue adapters implement
+ */
+export interface QueueWorkers {
+  /** Service name identifier */
+  name: string
+
+  /** Whether this queue service supports job results */
+  supportsResults: boolean
+
+  /** Configuration mapping for validation */
+  configMappings: QueueConfigMapping
+
+  /** Scan state and register all compatible processors */
+  registerQueues(): Promise<Record<string, ConfigValidationResult[]>>
+
+  /** Close all queues and connections */
+  close(): Promise<void>
+}
+
+/**
+ * Queue processor metadata
+ */
+export type queueWorkersMeta = Record<
+  string,
+  {
+    pikkuFuncName: string
+    schemaName?: string
+    queueName: string
+    session?: undefined
+    docs?: APIDocs
+    tags?: string[]
+    config?: PikkuWorkerConfig
+  }
+>
+
+/**
+ * Core queue processor definition
+ */
+export type CoreQueueWorker<
+  APIFunction = CoreAPIFunctionSessionless<any, any>,
+> = {
+  queueName: string
+  func: APIFunction
+  config?: PikkuWorkerConfig
+  docs?: APIDocs
+  session?: undefined
+  tags?: string[]
+}

package/src/events/queue/register-queue-helper.ts

@@ -0,0 +1,62 @@
+import type { ConfigValidationResult, CoreQueueWorker } from './queue.types.js'
+import { getQueueWorkers } from './queue-runner.js'
+import {
+  QueueConfigMapping,
+  validateWorkerConfig,
+} from './validate-worker-config.js'
+import { Logger } from '../../services/logger.js'
+
+/**
+ * Queue processor registration callback
+ */
+export type QueueRegistrationCallback<T = any> = (
+  queueName: string,
+  processor: CoreQueueWorker
+) => Promise<T>
+
+/**
+ * Helper function to register queue processors with validation
+ * This centralizes the common logic for looping over processors and validating configs
+ *
+ * @param configMappings - Configuration mapping for the queue implementation
+ * @param registerCallback - Callback to register each individual queue processor
+ * @param logger - Optional logger for info/error messages
+ * @returns Record of validation results by queue name
+ */
+export async function registerqueueWorkers<T = any>(
+  configMappings: QueueConfigMapping,
+  logger: Logger,
+  registerCallback: QueueRegistrationCallback<T>
+): Promise<Record<string, ConfigValidationResult[]>> {
+  const configValidation: Record<string, ConfigValidationResult[]> = {}
+  const queueWorkers = getQueueWorkers()
+
+  for (const [queueName, processor] of queueWorkers) {
+    logger?.info(`Registering queue processor: ${queueName}`)
+    // Validate the processor configuration
+    const validationResult = validateWorkerConfig(
+      configMappings,
+      processor.config
+    )
+
+    // Store validation results
+    configValidation[queueName] = configValidation[queueName] || []
+    configValidation[queueName].push(validationResult)
+
+    if (validationResult.warnings.length > 0) {
+      logger?.warn(
+        `Configuration warnings for queue ${queueName}:`,
+        validationResult.warnings
+      )
+    }
+
+    try {
+      await registerCallback(queueName, processor)
+      logger?.info(`Successfully registered queue processor: ${queueName}`)
+    } catch (error) {
+      logger?.error(`Failed to register queue processor ${queueName}:`, error)
+    }
+  }
+
+  return configValidation
+}

package/src/events/queue/validate-worker-config.ts

@@ -0,0 +1,113 @@
+import { PikkuWorkerConfig, ConfigValidationResult } from './queue.types.js'
+
+/**
+ * Configuration mapping structure for queue implementations
+ */
+export interface QueueConfigMapping {
+  /** Configurations that are directly supported */
+  supported: Partial<
+    Record<
+      keyof PikkuWorkerConfig,
+      {
+        /** The property name in the underlying queue system */
+        queueProperty?: string
+        /** Optional transform function for the value */
+        transform?: (value: any) => any
+        /** Description of what this configuration does */
+        description: string
+      }
+    >
+  >
+
+  /** Configurations that are not supported */
+  unsupported: Partial<
+    Record<
+      keyof PikkuWorkerConfig,
+      {
+        /** Why this configuration is not supported */
+        reason: string
+        /** Detailed explanation of what the queue system does instead */
+        explanation: string
+      }
+    >
+  >
+
+  /** Configurations that have partial support or workarounds */
+  fallbacks: Partial<
+    Record<
+      keyof PikkuWorkerConfig,
+      {
+        /** Why this configuration uses a fallback */
+        reason: string
+        /** Detailed explanation of the fallback behavior */
+        explanation: string
+        /** The fallback value or description */
+        fallbackValue: string
+      }
+    >
+  >
+}
+
+/**
+ * Validates worker configuration using a mapping table
+ * This provides a flexible, maintainable way to validate configurations
+ * across different queue implementations
+ *
+ * @param config - The worker configuration to validate
+ * @param configMapping - The mapping table defining supported/unsupported configurations
+ * @returns Validation result with applied, ignored, warnings, and fallbacks
+ */
+export function validateWorkerConfig(
+  configMapping: QueueConfigMapping,
+  config: PikkuWorkerConfig = {}
+): ConfigValidationResult {
+  const applied: Partial<PikkuWorkerConfig> = {}
+  const ignored: Partial<PikkuWorkerConfig> = {}
+  const warnings: string[] = []
+  const fallbacks: { [key: string]: any } = {}
+
+  // Process each configuration property
+  for (const [key, value] of Object.entries(config)) {
+    if (value === undefined) continue
+
+    const configKey = key as keyof PikkuWorkerConfig
+
+    // Check if it's a supported configuration
+    if (configKey in configMapping.supported) {
+      applied[configKey] = value
+      continue
+    }
+
+    // Check if it's a fallback configuration
+    if (configKey in configMapping.fallbacks) {
+      const fallbackMapping = configMapping.fallbacks[configKey]!
+      applied[configKey] = value
+      fallbacks[key] = fallbackMapping.fallbackValue
+      warnings.push(
+        `${key}: ${fallbackMapping.reason}. ${fallbackMapping.explanation}`
+      )
+      continue
+    }
+
+    // Check if it's an unsupported configuration
+    if (configKey in configMapping.unsupported) {
+      ignored[configKey] = value
+      const mapping = configMapping.unsupported[configKey]!
+      warnings.push(`${key}: ${mapping.reason}. ${mapping.explanation}`)
+      continue
+    }
+
+    // Unknown configuration
+    ignored[configKey] = value
+    warnings.push(
+      `${key}: Unknown configuration option for this queue implementation`
+    )
+  }
+
+  return {
+    applied,
+    ignored,
+    warnings,
+    fallbacks,
+  }
+}

package/src/events/rpc/index.ts

@@ -0,0 +1,2 @@
+export { initialize } from './rpc-runner.js'
+export type { PikkuRPC, RPCMeta } from './rpc-types.js'

package/src/{rpc → events/rpc}/rpc-runner.ts

@@ -1,6 +1,6 @@
-import { CoreServices } from '../types/core.types.js'
-import { runPikkuFunc } from '../function/function-runner.js'
-import { pikkuState } from '../pikku-state.js'
+import { CoreServices } from '../../types/core.types.js'
+import { runPikkuFunc } from '../../function/function-runner.js'
+import { pikkuState } from '../../pikku-state.js'
 import { RPCMeta } from './rpc-types.js'
 
 // Type for the RPC service configuration

package/src/events/scheduler/index.ts

@@ -0,0 +1,9 @@
+export * from './scheduler.types.js'
+
+export {
+  runScheduledTask,
+  addScheduledTask,
+  getScheduledTasks,
+} from './scheduler-runner.js'
+
+export * from './log-schedulers.js'

package/src/{scheduler → events/scheduler}/log-schedulers.ts

@@ -1,5 +1,5 @@
-import { pikkuState } from '../pikku-state.js'
-import { Logger } from '../services/index.js'
+import { pikkuState } from '../../pikku-state.js'
+import { Logger } from '../../services/index.js'
 
 /**
  * Logs all the loaded scheduled tasks.