digital-workers 2.1.3 → 2.4.0

package/src/approve.ts

@@ -1,5 +1,28 @@
 /**
  * Approval request functionality for digital workers
+ *
+ * IMPORTANT: Worker Routing vs LLM Content Generation
+ * ---------------------------------------------------
+ * This module provides real approval workflows, NOT LLM-generated approval content.
+ *
+ * - `digital-workers.approve()` - Routes approval requests to Workers (Humans
+ *   or AI Agents) via communication channels and waits for actual approval.
+ *
+ * - `ai-functions.approve()` - Generates approval request content via LLM
+ *   for use in human interaction UIs.
+ *
+ * Use digital-workers when you need:
+ * - Real approval workflows with actual approvers
+ * - Routing to specific people via Slack, email, SMS
+ * - Approval audit trails (who, when, via what channel)
+ * - Multi-approver workflows (any/all must approve)
+ *
+ * Use ai-functions when you need:
+ * - LLM-generated approval request content
+ * - Generating UI/UX for approval flows
+ * - Approval request templates
+ *
+ * @module
  */
 
 import type {
@@ -14,32 +37,41 @@ import type {
 } from './types.js'
 
 /**
- * Request approval from a worker or team
+ * Route an approval request to a Worker (Human or AI Agent) and wait for response.
  *
- * Routes approval requests through the specified channel and waits for a response.
+ * **Key Difference from ai-functions.approve():**
+ * Unlike `ai-functions.approve()` which generates approval request content
+ * using the LLM, this function routes the request to an actual approver via
+ * real communication channels (Slack, email, SMS) and waits for their response.
+ *
+ * This is a **workflow approval primitive**, not a content generation primitive.
  *
  * @param request - What is being requested for approval
- * @param target - The worker or team to request approval from
- * @param options - Approval options
- * @returns Promise resolving to approval result
+ * @param target - The worker or team to request approval from (routes to their channels)
+ * @param options - Approval options including channel, timeout, and context
+ * @returns Promise resolving to approval result with metadata (who approved, when, notes)
  *
  * @example
  * ```ts
- * // Request approval from a worker
+ * // Request approval from a human via Slack
  * const result = await approve('Expense: $500 for AWS', manager, {
  *   via: 'slack',
  *   context: { amount: 500, category: 'Infrastructure' },
  * })
  *
  * if (result.approved) {
- *   console.log(`Approved by ${result.approvedBy?.name}`)
+ *   console.log(`Approved by ${result.approvedBy?.name} at ${result.approvedAt}`)
  * }
  *
- * // Request approval from a team
+ * // Request approval from a team (routes to lead or available member)
  * const result = await approve('Deploy v2.1.0 to production', opsTeam, {
  *   via: 'slack',
  * })
  * ```
+ *
+ * @see {@link ai-functions#approve} for LLM-generated approval request content
+ * @see {@link approve.all} for multi-approver workflows (all must approve)
+ * @see {@link approve.any} for multi-approver workflows (any can approve)
  */
 export async function approve(
   request: string,
@@ -60,8 +92,8 @@ export async function approve(
 
   // Send the approval request and wait for response
   const response = await sendApprovalRequest(channel, request, contacts, {
-    timeout,
-    context,
+    ...(timeout !== undefined && { timeout }),
+    ...(context !== undefined && { context }),
     approver,
     escalate,
   })
@@ -70,7 +102,7 @@ export async function approve(
     approved: response.approved,
     approvedBy: approver,
     approvedAt: new Date(),
-    notes: response.notes,
+    ...(response.notes !== undefined && { notes: response.notes }),
     via: channel,
   }
 }
@@ -300,18 +332,57 @@ async function sendApprovalRequest(
     throw new Error(`No ${channel} contact configured`)
   }
 
-  // In a real implementation, this would:
-  // 1. Format the request for the channel (Slack blocks, email HTML, etc.)
-  // 2. Send via the appropriate API
-  // 3. Wait for response (polling, webhook, interactive message, etc.)
-  // 4. Handle timeout and escalation
+  // Import transport functions dynamically to avoid circular dependencies
+  const { channelToTransport, sendViaTransport, hasTransport, resolveAddress } = await import(
+    './transports.js'
+  )
 
-  // For now, simulate a pending response
-  await new Promise((resolve) => setTimeout(resolve, 10))
+  const transport = channelToTransport(channel)
+  const address = resolveAddress(contacts, channel)
+
+  // If transport is registered, use it for real delivery
+  if (hasTransport(transport) && address) {
+    const { generateRequestId } = await import('./utils/id.js')
+    const requestId = generateRequestId('apr')
+
+    const payload = {
+      to: address.value,
+      body: request,
+      type: 'approval' as const,
+      priority: 'normal' as const,
+      threadId: requestId,
+      actions: [
+        { id: 'approve', label: 'Approve', style: 'primary' as const, value: true },
+        { id: 'reject', label: 'Reject', style: 'danger' as const, value: false },
+      ],
+      metadata: {
+        ...options.context,
+        approver: options.approver,
+        escalate: options.escalate,
+      },
+      ...(options.timeout !== undefined && { timeout: options.timeout }),
+    }
+
+    const result = await sendViaTransport(transport, payload)
+
+    if (result.success) {
+      // For real transports, we need to wait for a response
+      // This would integrate with the runtime's HumanRequestProcessor
+      // For now, return pending state - the response comes via webhook
+      return {
+        approved: false,
+        notes: `Approval request sent via ${transport}. Awaiting response. Request ID: ${requestId}`,
+      }
+    } else {
+      throw new Error(`Failed to send approval request via ${transport}: ${result.error}`)
+    }
+  }
 
-  // Return a placeholder - real impl would wait for actual response
+  // No transport registered - return pending state
+  // In a real workflow, this would be processed when a transport is configured
+  // or the runtime handles the request via HumanRequestProcessor
   return {
     approved: false,
-    notes: 'Approval pending - waiting for response',
+    notes: `Approval request pending - no transport registered for ${channel}. Configure a transport handler to enable real delivery.`,
   }
 }

package/src/ask.ts

@@ -1,5 +1,27 @@
 /**
  * Question/answer functionality for digital workers
+ *
+ * IMPORTANT: Worker Routing vs Direct LLM Calls
+ * ---------------------------------------------
+ * This module provides worker-routed question handling, NOT direct LLM queries.
+ *
+ * - `digital-workers.ask()` - Routes questions to Workers (AI Agents or Humans)
+ *   via communication channels (Slack, email, SMS, etc.) and waits for response.
+ *
+ * - `ai-functions.ask()` - Generates content for human interaction via LLM.
+ *
+ * Use digital-workers when you need:
+ * - To ask a specific person or team via real channels
+ * - Human responses with accountability (who answered)
+ * - Channel-based communication (Slack, email, SMS)
+ * - Team coordination and escalation
+ *
+ * Use ai-functions when you need:
+ * - LLM-generated question/answer content
+ * - Generating UI for human input
+ * - Direct AI text generation
+ *
+ * @module
  */
 
 import { generateObject } from 'ai-functions'
@@ -16,24 +38,31 @@ import type {
 } from './types.js'
 
 /**
- * Ask a question to a worker or team
+ * Route a question to a Worker (AI Agent or Human) via communication channels.
  *
- * Routes questions through the specified channel and waits for a response.
+ * **Key Difference from ai-functions.ask():**
+ * Unlike `ai-functions.ask()` which generates content for human interaction
+ * using the LLM, this function routes the question to an actual Worker (person
+ * or AI agent) via real communication channels (Slack, email, SMS, etc.) and
+ * waits for their response.
  *
- * @param target - The worker or team to ask
+ * This is a **worker communication primitive**, not a direct LLM primitive.
+ *
+ * @param target - The worker or team to ask (routes to their configured channels)
  * @param question - The question to ask
- * @param options - Ask options
- * @returns Promise resolving to the answer
+ * @param options - Ask options including channel, schema, and timeout
+ * @returns Promise resolving to the answer with metadata (who answered, when, via what channel)
  *
  * @example
  * ```ts
- * // Ask a simple question
+ * // Ask a human via Slack
  * const result = await ask(alice, 'What is the company holiday policy?', {
  *   via: 'slack',
  * })
  * console.log(result.answer)
+ * console.log(`Answered by ${result.answeredBy.name} at ${result.answeredAt}`)
  *
- * // Ask with structured response
+ * // Ask with structured response schema
  * const result = await ask(ceo, 'What are our Q1 priorities?', {
  *   via: 'email',
  *   schema: {
@@ -42,6 +71,8 @@ import type {
  *   },
  * })
  * ```
+ *
+ * @see {@link ai-functions#ask} for LLM-generated human interaction content
  */
 export async function ask<T = string>(
   target: ActionTarget,
@@ -62,9 +93,9 @@ export async function ask<T = string>(
 
   // Send the question and wait for response
   const response = await sendQuestion<T>(channel, question, contacts, {
-    schema,
-    timeout,
-    context,
+    ...(schema !== undefined && { schema }),
+    ...(timeout !== undefined && { timeout }),
+    ...(context !== undefined && { context }),
     recipient,
   })
 
@@ -97,9 +128,13 @@ ask.ai = async <T = string>(
       model: 'sonnet',
       schema,
       prompt: question,
-      system: context
-        ? `Use the following context to answer the question:\n\n${JSON.stringify(context, null, 2)}`
-        : undefined,
+      ...(context !== undefined && {
+        system: `Use the following context to answer the question:\n\n${JSON.stringify(
+          context,
+          null,
+          2
+        )}`,
+      }),
     })
     return result.object as T
   }
@@ -108,9 +143,13 @@ ask.ai = async <T = string>(
     model: 'sonnet',
     schema: { answer: 'The answer to the question' },
     prompt: question,
-    system: context
-      ? `Use the following context to answer the question:\n\n${JSON.stringify(context, null, 2)}`
-      : undefined,
+    ...(context !== undefined && {
+      system: `Use the following context to answer the question:\n\n${JSON.stringify(
+        context,
+        null,
+        2
+      )}`,
+    }),
   })
 
   return (result.object as { answer: T }).answer
@@ -288,17 +327,52 @@ async function sendQuestion<T>(
     throw new Error(`No ${channel} contact configured`)
   }
 
-  // In a real implementation, this would:
-  // 1. Format the question for the channel
-  // 2. Send via the appropriate API
-  // 3. Wait for response (polling, webhook, etc.)
-  // 4. Parse and validate the response
+  // Import transport functions dynamically to avoid circular dependencies
+  const { channelToTransport, sendViaTransport, hasTransport, resolveAddress } = await import(
+    './transports.js'
+  )
 
-  // For now, simulate a pending response
-  await new Promise((resolve) => setTimeout(resolve, 10))
+  const transport = channelToTransport(channel)
+  const address = resolveAddress(contacts, channel)
+
+  // If transport is registered, use it for real delivery
+  if (hasTransport(transport) && address) {
+    const { generateRequestId } = await import('./utils/id.js')
+    const requestId = generateRequestId('ask')
+
+    const payload = {
+      to: address.value,
+      body: question,
+      type: 'question' as const,
+      priority: 'normal' as const,
+      threadId: requestId,
+      ...(options.schema !== undefined && { schema: options.schema }),
+      ...(options.timeout !== undefined && { timeout: options.timeout }),
+      metadata: {
+        ...options.context,
+        recipient: options.recipient,
+      },
+    }
+
+    const result = await sendViaTransport(transport, payload)
+
+    if (result.success) {
+      // For real transports, we need to wait for a response
+      // This would integrate with the runtime's HumanRequestProcessor
+      // For now, return pending state - the response comes via webhook
+      return {
+        answer: `Question sent via ${transport}. Awaiting response. Request ID: ${requestId}` as T,
+      }
+    } else {
+      throw new Error(`Failed to send question via ${transport}: ${result.error}`)
+    }
+  }
 
-  // Return a placeholder - real impl would wait for actual response
+  // No transport registered - return pending state
+  // In a real workflow, this would be processed when a transport is configured
+  // or the runtime handles the request via HumanRequestProcessor
   return {
-    answer: 'Waiting for response...' as T,
+    answer:
+      `Question pending - no transport registered for ${channel}. Configure a transport handler to enable real delivery.` as T,
   }
 }