digital-workers 2.1.3 → 2.3.0

package/src/load-balancing.ts

@@ -167,6 +167,38 @@ export interface MetricsCollector {
   reset(): void
 }
 
+// ============================================================================
+// Safe Array Access Utilities
+// ============================================================================
+
+/**
+ * Safely get the first element of an array.
+ *
+ * Provides type-safe access to array elements without non-null assertions.
+ *
+ * @param arr - The array to access
+ * @returns The first element or undefined if array is empty
+ */
+function safeFirst<T>(arr: T[]): T | undefined {
+  return arr.length > 0 ? arr[0] : undefined
+}
+
+/**
+ * Safely get an element at a specific index.
+ *
+ * Provides type-safe access with bounds checking.
+ *
+ * @param arr - The array to access
+ * @param index - The index to access
+ * @returns The element at the index or undefined if out of bounds
+ */
+function safeAt<T>(arr: T[], index: number): T | undefined {
+  if (arr.length === 0 || index < 0 || index >= arr.length) {
+    return undefined
+  }
+  return arr[index]
+}
+
 // ============================================================================
 // MetricsCollector Implementation
 // ============================================================================
@@ -213,11 +245,7 @@ export function createMetricsCollector(): MetricsCollector {
   }
   let totalLatency = 0
 
-  function record(
-    result: RouteResult,
-    latencyMs: number,
-    strategy: BalancerStrategy
-  ): void {
+  function record(result: RouteResult, latencyMs: number, strategy: BalancerStrategy): void {
     metricsState.totalRouted++
     totalLatency += latencyMs
     metricsState.averageLatencyMs = totalLatency / metricsState.totalRouted
@@ -326,7 +354,7 @@ export function createRoundRobinBalancer(
   const collector = options.metricsCollector ?? defaultMetricsCollector
 
   function getAvailableAgents(): AgentInfo[] {
-    return agents.filter(a => a.status === 'available' || a.status === 'busy')
+    return agents.filter((a) => a.status === 'available' || a.status === 'busy')
   }
 
   function route(task: TaskRequest): RouteResult {
@@ -348,8 +376,12 @@ export function createRoundRobinBalancer(
     // Find the next available agent starting from current index
     let attempts = 0
     while (attempts < agents.length) {
-      const agent = agents[currentIndex % agents.length]!
+      const agent = safeAt(agents, currentIndex % agents.length)
       currentIndex++
+      if (!agent) {
+        attempts++
+        continue
+      }
 
       if (agent.status === 'available' || agent.status === 'busy') {
         const result: RouteResult = {
@@ -380,7 +412,7 @@ export function createRoundRobinBalancer(
   }
 
   function removeAgent(agentId: string): void {
-    agents = agents.filter(a => a.id !== agentId)
+    agents = agents.filter((a) => a.id !== agentId)
   }
 
   function getAgents(): AgentInfo[] {
@@ -430,10 +462,10 @@ export function createLeastBusyBalancer(
   const collector = options.metricsCollector ?? defaultMetricsCollector
 
   // Initialize load tracking
-  agents.forEach(a => loadTracking.set(a.id, a.currentLoad))
+  agents.forEach((a) => loadTracking.set(a.id, a.currentLoad))
 
   function getAvailableAgents(): AgentInfo[] {
-    return agents.filter(a => {
+    return agents.filter((a) => {
       if (a.status !== 'available' && a.status !== 'busy') return false
       const load = loadTracking.get(a.id) ?? a.currentLoad
       return load < a.maxLoad
@@ -471,7 +503,18 @@ export function createLeastBusyBalancer(
       return loadA - loadB
     })
 
-    const selected = sorted[0]!
+    const selected = safeFirst(sorted)
+    if (!selected) {
+      const result: RouteResult = {
+        agent: null,
+        task,
+        strategy: 'least-busy',
+        timestamp: new Date(),
+        reason: 'no-available-agents',
+      }
+      collector.record(result, performance.now() - start, 'least-busy')
+      return result
+    }
     lastRoutedIndex = agents.indexOf(selected)
 
     // Increment load
@@ -494,7 +537,7 @@ export function createLeastBusyBalancer(
   }
 
   function removeAgent(agentId: string): void {
-    agents = agents.filter(a => a.id !== agentId)
+    agents = agents.filter((a) => a.id !== agentId)
     loadTracking.delete(agentId)
   }
 
@@ -504,7 +547,7 @@ export function createLeastBusyBalancer(
 
   function getLoadMetrics(): Record<string, number> {
     const metrics: Record<string, number> = {}
-    agents.forEach(a => {
+    agents.forEach((a) => {
       const load = loadTracking.get(a.id) ?? a.currentLoad
       metrics[a.id] = load / a.maxLoad
     })
@@ -566,16 +609,16 @@ export function createCapabilityRouter(
   const collector = options.metricsCollector ?? defaultMetricsCollector
 
   function getAvailableAgents(): AgentInfo[] {
-    return agents.filter(a => a.status === 'available' || a.status === 'busy')
+    return agents.filter((a) => a.status === 'available' || a.status === 'busy')
   }
 
   function hasAllSkills(agent: AgentInfo, requiredSkills: string[]): boolean {
-    return requiredSkills.every(skill => agent.skills.includes(skill))
+    return requiredSkills.every((skill) => agent.skills.includes(skill))
   }
 
   function calculateMatchScore(agent: AgentInfo, requiredSkills: string[]): number {
     if (requiredSkills.length === 0) return 1
-    const matchingSkills = requiredSkills.filter(s => agent.skills.includes(s))
+    const matchingSkills = requiredSkills.filter((s) => agent.skills.includes(s))
     return matchingSkills.length / requiredSkills.length
   }
 
@@ -584,7 +627,7 @@ export function createCapabilityRouter(
     const available = getAvailableAgents()
 
     // Find agents with all required skills
-    let candidates = available.filter(a => hasAllSkills(a, task.requiredSkills))
+    let candidates = available.filter((a) => hasAllSkills(a, task.requiredSkills))
 
     if (candidates.length === 0) {
       const result: RouteResult = {
@@ -608,7 +651,18 @@ export function createCapabilityRouter(
       })
     }
 
-    const selected = candidates[0]!
+    const selected = safeFirst(candidates)
+    if (!selected) {
+      const result: RouteResult = {
+        agent: null,
+        task,
+        strategy: 'capability',
+        timestamp: new Date(),
+        reason: 'no-matching-capability',
+      }
+      collector.record(result, performance.now() - start, 'capability')
+      return result
+    }
     const matchScore = calculateMatchScore(selected, task.requiredSkills)
 
     const result: RouteResult = {
@@ -627,7 +681,7 @@ export function createCapabilityRouter(
   }
 
   function removeAgent(agentId: string): void {
-    agents = agents.filter(a => a.id !== agentId)
+    agents = agents.filter((a) => a.id !== agentId)
   }
 
   function getAgents(): AgentInfo[] {
@@ -635,13 +689,13 @@ export function createCapabilityRouter(
   }
 
   function findAgentsWithSkills(skills: string[]): AgentInfo[] {
-    return agents.filter(a => hasAllSkills(a, skills))
+    return agents.filter((a) => hasAllSkills(a, skills))
   }
 
   function getSkillCoverage(): Record<string, number> {
     const coverage: Record<string, number> = {}
-    agents.forEach(a => {
-      a.skills.forEach(skill => {
+    agents.forEach((a) => {
+      a.skills.forEach((skill) => {
         coverage[skill] = (coverage[skill] || 0) + 1
       })
     })
@@ -706,11 +760,11 @@ export function createPriorityQueueBalancer(
   const collector = options.metricsCollector ?? defaultMetricsCollector
 
   function getAvailableAgents(): AgentInfo[] {
-    return agents.filter(a => a.status === 'available' || a.status === 'busy')
+    return agents.filter((a) => a.status === 'available' || a.status === 'busy')
   }
 
   function getEffectivePriority(taskId: string): number {
-    const task = queue.find(t => t.id === taskId)
+    const task = queue.find((t) => t.id === taskId)
     if (!task) return 0
 
     let priority = task.priority
@@ -758,7 +812,8 @@ export function createPriorityQueueBalancer(
     if (queue.length === 0) return null
 
     sortQueue()
-    const task = queue.shift()!
+    const task = queue.shift()
+    if (!task) return null
     const start = performance.now()
     const available = getAvailableAgents()
 
@@ -775,7 +830,18 @@ export function createPriorityQueueBalancer(
     }
 
     // Simple round-robin among available for now
-    const agent = available[0]!
+    const agent = safeFirst(available)
+    if (!agent) {
+      const result: RouteResult = {
+        agent: null,
+        task,
+        strategy: 'priority-queue',
+        timestamp: new Date(),
+        reason: 'no-available-agents',
+      }
+      collector.record(result, performance.now() - start, 'priority-queue')
+      return result
+    }
 
     const result: RouteResult = {
       agent,
@@ -803,7 +869,18 @@ export function createPriorityQueueBalancer(
       return result
     }
 
-    const agent = available[0]!
+    const agent = safeFirst(available)
+    if (!agent) {
+      const result: RouteResult = {
+        agent: null,
+        task,
+        strategy: 'priority-queue',
+        timestamp: new Date(),
+        reason: 'no-available-agents',
+      }
+      collector.record(result, performance.now() - start, 'priority-queue')
+      return result
+    }
     const result: RouteResult = {
       agent,
       task,
@@ -819,7 +896,7 @@ export function createPriorityQueueBalancer(
   }
 
   function removeAgent(agentId: string): void {
-    agents = agents.filter(a => a.id !== agentId)
+    agents = agents.filter((a) => a.id !== agentId)
   }
 
   function getAgents(): AgentInfo[] {
@@ -903,7 +980,7 @@ export function createAgentAvailabilityTracker(
   const { heartbeatTimeout = 30000 } = options
 
   // Initialize
-  initialAgents.forEach(a => {
+  initialAgents.forEach((a) => {
     agents.set(a.id, a)
     availability.set(a.id, {
       status: a.status,
@@ -914,10 +991,12 @@ export function createAgentAvailabilityTracker(
   })
 
   function getAvailability(agentId: string): AgentAvailability {
-    return availability.get(agentId) ?? {
-      status: 'offline',
-      lastSeen: new Date(0),
-    }
+    return (
+      availability.get(agentId) ?? {
+        status: 'offline',
+        lastSeen: new Date(0),
+      }
+    )
   }
 
   function updateStatus(agentId: string, status: WorkerStatus): void {
@@ -943,12 +1022,12 @@ export function createAgentAvailabilityTracker(
         currentStatus: status,
         timestamp: new Date(),
       }
-      handlers.forEach(h => h(event))
+      handlers.forEach((h) => h(event))
     }
   }
 
   function getAvailableAgents(): AgentInfo[] {
-    return Array.from(agents.values()).filter(a => {
+    return Array.from(agents.values()).filter((a) => {
       const avail = availability.get(a.id)
       return avail?.status === 'available' || avail?.status === 'busy'
     })
@@ -1137,7 +1216,7 @@ export function createRoutingRuleEngine(
 
     // Sort rules by priority (descending)
     const sortedRules = [...rules]
-      .filter(r => r.enabled !== false)
+      .filter((r) => r.enabled !== false)
       .sort((a, b) => b.priority - a.priority)
 
     // Evaluate rules
@@ -1178,28 +1257,28 @@ export function createRoutingRuleEngine(
   }
 
   function removeRule(name: string): void {
-    const index = rules.findIndex(r => r.name === name)
+    const index = rules.findIndex((r) => r.name === name)
     if (index !== -1) {
       rules.splice(index, 1)
     }
   }
 
   function updateRule(name: string, updates: Partial<RoutingRule>): void {
-    const rule = rules.find(r => r.name === name)
+    const rule = rules.find((r) => r.name === name)
     if (rule) {
       Object.assign(rule, updates)
     }
   }
 
   function enableRule(name: string): void {
-    const rule = rules.find(r => r.name === name)
+    const rule = rules.find((r) => r.name === name)
     if (rule) {
       rule.enabled = true
     }
   }
 
   function disableRule(name: string): void {
-    const rule = rules.find(r => r.name === name)
+    const rule = rules.find((r) => r.name === name)
     if (rule) {
       rule.enabled = false
     }
@@ -1215,7 +1294,7 @@ export function createRoutingRuleEngine(
   }
 
   function removeAgent(agentId: string): void {
-    agents = agents.filter(a => a.id !== agentId)
+    agents = agents.filter((a) => a.id !== agentId)
     defaultBalancer = undefined as any // Reset default balancer
   }
 
@@ -1283,7 +1362,14 @@ export function createCompositeBalancer(
           balancers.set(strategy, createRoundRobinBalancer(agents, balancerOptions))
       }
     }
-    return balancers.get(strategy)!
+    const balancer = balancers.get(strategy)
+    if (!balancer) {
+      // Fallback to round-robin if strategy not found
+      const fallback = createRoundRobinBalancer(agents, { metricsCollector: collector })
+      balancers.set(strategy, fallback)
+      return fallback
+    }
+    return balancer
   }
 
   function route(task: TaskRequest): RouteResult {
@@ -1293,7 +1379,7 @@ export function createCompositeBalancer(
     let usedFallback = false
 
     // Handle weighted strategies
-    const weightedStrategies = config.strategies.map(s => {
+    const weightedStrategies = config.strategies.map((s) => {
       if (typeof s === 'string') {
         return { strategy: s, weight: 1 }
       }
@@ -1365,12 +1451,12 @@ export function createCompositeBalancer(
 
   function addAgent(agent: AgentInfo): void {
     agents.push(agent)
-    balancers.forEach(b => b.addAgent(agent))
+    balancers.forEach((b) => b.addAgent(agent))
   }
 
   function removeAgent(agentId: string): void {
-    agents = agents.filter(a => a.id !== agentId)
-    balancers.forEach(b => b.removeAgent(agentId))
+    agents = agents.filter((a) => a.id !== agentId)
+    balancers.forEach((b) => b.removeAgent(agentId))
   }
 
   function getAgents(): AgentInfo[] {

package/src/logger.ts

@@ -0,0 +1,93 @@
+/**
+ * Logger Interface for Digital Workers
+ *
+ * Provides a simple, extensible logging interface that can be injected
+ * into components for error logging and debugging. Consumers can provide
+ * their own logger implementation (e.g., winston, pino, console).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Logger interface for structured logging
+ *
+ * @example
+ * ```typescript
+ * // Using with console
+ * const consoleLogger: Logger = {
+ *   debug: (msg, meta) => console.debug(msg, meta),
+ *   info: (msg, meta) => console.info(msg, meta),
+ *   warn: (msg, meta) => console.warn(msg, meta),
+ *   error: (msg, error, meta) => console.error(msg, error, meta),
+ * }
+ *
+ * // Using with a custom logger
+ * const customLogger: Logger = {
+ *   debug: (msg, meta) => myLogger.debug({ message: msg, ...meta }),
+ *   info: (msg, meta) => myLogger.info({ message: msg, ...meta }),
+ *   warn: (msg, meta) => myLogger.warn({ message: msg, ...meta }),
+ *   error: (msg, error, meta) => myLogger.error({ message: msg, error, ...meta }),
+ * }
+ * ```
+ */
+export interface Logger {
+  /**
+   * Log debug-level messages
+   * @param msg - The log message
+   * @param meta - Optional metadata object
+   */
+  debug(msg: string, meta?: object): void
+
+  /**
+   * Log info-level messages
+   * @param msg - The log message
+   * @param meta - Optional metadata object
+   */
+  info(msg: string, meta?: object): void
+
+  /**
+   * Log warning-level messages
+   * @param msg - The log message
+   * @param meta - Optional metadata object
+   */
+  warn(msg: string, meta?: object): void
+
+  /**
+   * Log error-level messages
+   * @param msg - The log message
+   * @param error - Optional error object with stack trace
+   * @param meta - Optional metadata object
+   */
+  error(msg: string, error?: Error, meta?: object): void
+}
+
+/**
+ * A no-op logger that discards all log messages.
+ * Used as a default when no logger is provided.
+ */
+export const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+}
+
+/**
+ * Creates a console-based logger for debugging purposes.
+ *
+ * @example
+ * ```typescript
+ * const transport = createSlackTransport({
+ *   ...config,
+ *   logger: createConsoleLogger(),
+ * })
+ * ```
+ */
+export function createConsoleLogger(): Logger {
+  return {
+    debug: (msg, meta) => console.debug(`[DEBUG] ${msg}`, meta ?? ''),
+    info: (msg, meta) => console.info(`[INFO] ${msg}`, meta ?? ''),
+    warn: (msg, meta) => console.warn(`[WARN] ${msg}`, meta ?? ''),
+    error: (msg, error, meta) => console.error(`[ERROR] ${msg}`, error ?? '', meta ?? ''),
+  }
+}

package/src/notify.ts

@@ -1,7 +1,28 @@
 /**
  * Notification functionality for digital workers
+ *
+ * IMPORTANT: Real Channel Delivery vs LLM Generation
+ * ---------------------------------------------------
+ * This module sends real notifications via communication channels,
+ * NOT LLM-generated notification content.
+ *
+ * - `digital-workers.notify()` - Sends actual notifications to Workers
+ *   via real channels (Slack, email, SMS, etc.) with delivery tracking.
+ *
+ * - ai-functions does not have an equivalent `notify` primitive since
+ *   it focuses on LLM operations, not communication channel delivery.
+ *
+ * Use digital-workers.notify() when you need:
+ * - Real notification delivery to people/agents
+ * - Multi-channel delivery (Slack + SMS for urgent)
+ * - Delivery tracking and confirmation
+ * - Priority-based channel selection
+ * - Scheduled notifications
+ *
+ * @module
  */
 
+import { generateRequestId } from './utils/id.js'
 import type {
   Worker,
   Team,
@@ -14,30 +35,39 @@ import type {
 } from './types.js'
 
 /**
- * Send a notification to a worker or team
+ * Send a notification to a Worker (Human or AI Agent) via communication channels.
+ *
+ * **Unique to digital-workers:**
+ * This function sends real notifications via actual communication channels
+ * (Slack, email, SMS, phone, etc.). There is no equivalent in ai-functions
+ * since ai-functions focuses on LLM operations rather than external delivery.
  *
- * Routes notifications through the specified channel(s), falling back
- * to the target's preferred channel if not specified.
+ * This is a **communication delivery primitive** for worker coordination.
  *
- * @param target - The worker or team to notify
+ * @param target - The worker or team to notify (routes to their configured channels)
  * @param message - The notification message
- * @param options - Notification options
- * @returns Promise resolving to notification result
+ * @param options - Notification options (channel, priority, metadata)
+ * @returns Promise resolving to NotifyResult with delivery status and metadata
  *
  * @example
  * ```ts
  * // Notify a worker via their preferred channel
- * await notify(alice, 'Deployment completed successfully')
+ * const result = await notify(alice, 'Deployment completed successfully')
+ * console.log(result.sent) // true
+ * console.log(result.via) // ['slack']
  *
  * // Notify via specific channel
  * await notify(alice, 'Urgent: Server down!', { via: 'slack' })
  *
- * // Notify via multiple channels
+ * // Notify via multiple channels (for urgent messages)
  * await notify(alice, 'Critical alert', { via: ['slack', 'sms'] })
  *
- * // Notify a team
+ * // Notify a team (reaches all members via their channels)
  * await notify(engineering, 'Sprint planning tomorrow', { via: 'slack' })
  * ```
+ *
+ * @see {@link notify.alert} for high-priority urgent notifications
+ * @see {@link notify.schedule} for delayed/scheduled notifications
  */
 export async function notify(
   target: ActionTarget,
@@ -66,7 +96,10 @@ export async function notify(
   const delivery = await Promise.all(
     channels.map(async (channel) => {
       try {
-        await sendToChannel(channel, message, contacts, { priority, metadata })
+        await sendToChannel(channel, message, contacts, {
+          priority,
+          ...(metadata !== undefined && { metadata }),
+        })
         return { channel, status: 'sent' as const }
       } catch (error) {
         return {
@@ -286,18 +319,46 @@ async function sendToChannel(
     throw new Error(`No ${channel} contact configured`)
   }
 
-  // In a real implementation, this would:
-  // 1. Format the message for the channel
-  // 2. Send via the appropriate API (Slack, SendGrid, Twilio, etc.)
-  // 3. Handle delivery confirmation
+  // Import transport functions dynamically to avoid circular dependencies
+  const { channelToTransport, sendViaTransport, hasTransport, resolveAddress } = await import(
+    './transports.js'
+  )
+
+  const transport = channelToTransport(channel)
+  const address = resolveAddress(contacts, channel)
+
+  // If transport is registered, use it for real delivery
+  if (hasTransport(transport) && address) {
+    const payload = {
+      to: address.value,
+      body: message,
+      type: 'notification' as const,
+      priority: (options.priority || 'normal') as 'low' | 'normal' | 'high' | 'urgent',
+      ...(options.metadata !== undefined && { metadata: options.metadata }),
+    }
+
+    const result = await sendViaTransport(transport, payload)
+
+    if (!result.success) {
+      throw new Error(`Failed to send notification via ${transport}: ${result.error}`)
+    }
+    return
+  }
 
-  // For now, simulate success
-  await new Promise((resolve) => setTimeout(resolve, 10))
+  // No transport registered - log to console for development/testing
+  // This provides visibility into what would be sent
+  console.log(`[digital-workers] Notification (${channel}):`, {
+    to: typeof contact === 'string' ? contact : JSON.stringify(contact),
+    message,
+    priority: options.priority || 'normal',
+    metadata: options.metadata,
+    note: `No transport registered for '${transport}'. Register a transport handler to enable real delivery.`,
+  })
 }
 
 /**
  * Generate a unique message ID
  */
 function generateMessageId(prefix = 'msg'): string {
-  return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+  return generateRequestId(prefix)
 }