digital-workers 2.1.1 → 2.3.0

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)
 }

package/src/role.ts

@@ -4,6 +4,8 @@
 
 import type { WorkerRole } from './types.js'
 
+// Note: Role type is re-exported from types.ts which imports from org.ai
+
 /**
  * Define a worker role
  *
@@ -15,7 +17,7 @@ import type { WorkerRole } from './types.js'
  *
  * @example
  * ```ts
- * const engineer = Role({
+ * const engineer = defineRole({
  *   name: 'Software Engineer',
  *   description: 'Builds and maintains software systems',
  *   responsibilities: [
@@ -31,7 +33,7 @@ import type { WorkerRole } from './types.js'
  *
  * @example
  * ```ts
- * const supportAgent = Role({
+ * const supportAgent = defineRole({
  *   name: 'Customer Support Agent',
  *   description: 'Assists customers with inquiries and issues',
  *   responsibilities: [
@@ -44,11 +46,13 @@ import type { WorkerRole } from './types.js'
  * })
  * ```
  */
-export function Role(definition: Omit<WorkerRole, 'type'> & { type?: WorkerRole['type'] }): WorkerRole {
+export function defineRole(
+  definition: Omit<WorkerRole, 'type'> & { type?: WorkerRole['type'] }
+): WorkerRole {
   return {
-    type: 'hybrid', // Default to hybrid (can be AI or human)
     ...definition,
-  }
+    type: definition.type ?? 'hybrid',
+  } as WorkerRole
 }
 
 /**
@@ -56,7 +60,7 @@ export function Role(definition: Omit<WorkerRole, 'type'> & { type?: WorkerRole[
  *
  * @example
  * ```ts
- * const dataAnalyst = Role.ai({
+ * const dataAnalyst = defineRole.ai({
  *   name: 'Data Analyst',
  *   description: 'Analyzes data and generates insights',
  *   responsibilities: [
@@ -67,17 +71,18 @@ export function Role(definition: Omit<WorkerRole, 'type'> & { type?: WorkerRole[
  * })
  * ```
  */
-Role.ai = (definition: Omit<WorkerRole, 'type'>): WorkerRole => ({
-  ...definition,
-  type: 'ai',
-})
+defineRole.ai = (definition: Omit<WorkerRole, 'type'>): WorkerRole =>
+  ({
+    ...definition,
+    type: 'ai',
+  } as WorkerRole)
 
 /**
  * Create a human-specific role
  *
  * @example
  * ```ts
- * const manager = Role.human({
+ * const manager = defineRole.human({
  *   name: 'Engineering Manager',
  *   description: 'Leads engineering team and makes strategic decisions',
  *   responsibilities: [
@@ -89,17 +94,18 @@ Role.ai = (definition: Omit<WorkerRole, 'type'>): WorkerRole => ({
  * })
  * ```
  */
-Role.human = (definition: Omit<WorkerRole, 'type'>): WorkerRole => ({
-  ...definition,
-  type: 'human',
-})
+defineRole.human = (definition: Omit<WorkerRole, 'type'>): WorkerRole =>
+  ({
+    ...definition,
+    type: 'human',
+  } as WorkerRole)
 
 /**
  * Create a hybrid role (can be AI or human)
  *
  * @example
  * ```ts
- * const contentWriter = Role.hybrid({
+ * const contentWriter = defineRole.hybrid({
  *   name: 'Content Writer',
  *   description: 'Creates written content for various channels',
  *   responsibilities: [
@@ -110,7 +116,11 @@ Role.human = (definition: Omit<WorkerRole, 'type'>): WorkerRole => ({
  * })
  * ```
  */
-Role.hybrid = (definition: Omit<WorkerRole, 'type'>): WorkerRole => ({
-  ...definition,
-  type: 'hybrid',
-})
+defineRole.hybrid = (definition: Omit<WorkerRole, 'type'>): WorkerRole =>
+  ({
+    ...definition,
+    type: 'hybrid',
+  } as WorkerRole)
+
+// Legacy alias for backward compatibility
+export { defineRole as Role }