digital-workers 2.1.1 → 2.3.0

package/src/index.ts

@@ -6,7 +6,29 @@
  * defines a unified Worker interface that enables workflows to be designed
  * once and executed by any combination of AI and human workers.
  *
- * Package relationships:
+ * ## Worker Routing vs ai-functions Primitives
+ *
+ * **IMPORTANT:** This package exports functions that overlap in name with
+ * `ai-functions` primitives (do, ask, decide, approve, generate, is) but
+ * serve fundamentally different purposes:
+ *
+ * | Function | digital-workers | ai-functions |
+ * |----------|----------------|--------------|
+ * | `do` | Routes tasks to Workers | Direct LLM task description |
+ * | `ask` | Routes questions via Slack/email | LLM content for human UI |
+ * | `decide` | Multi-criteria decision framework | LLM-as-judge comparison |
+ * | `approve` | Real approval workflow via channels | LLM-generated approval content |
+ * | `generate` | Content generation with metadata | Core LLM generation primitive |
+ * | `is` | Type/schema validation with errors | Boolean assertion via LLM |
+ * | `notify` | Real channel delivery | (no equivalent) |
+ *
+ * **digital-workers functions are worker coordination primitives** that route
+ * work to AI Agents or Humans via real communication channels.
+ *
+ * **ai-functions primitives are direct LLM operations** for text generation,
+ * decision-making, and content creation.
+ *
+ * ## Package relationships:
  * - `autonomous-agents` - Implements Worker for AI agents
  * - `human-in-the-loop` - Implements Worker for humans
  * - `ai-workflows` - Uses digital-workers to orchestrate execution
@@ -32,12 +54,13 @@
  *   const worker$ = withWorkers($)
  *
  *   $.on.Expense.submitted(async (expense) => {
+ *     // These route to REAL workers via REAL channels
  *     await worker$.notify(finance, `New expense: ${expense.amount}`)
  *
  *     const approval = await worker$.approve(
  *       `Expense: $${expense.amount}`,
  *       manager,
- *       { via: 'slack' }
+ *       { via: 'slack' }  // Actually sends to Slack!
  *     )
  *
  *     if (approval.approved) {
@@ -72,18 +95,103 @@ export {
 export { Role } from './role.js'
 export { Team } from './team.js'
 export { Goals } from './goals.js'
+
+/**
+ * Worker Routing Functions
+ *
+ * These functions route work to Workers (AI Agents or Humans) via real
+ * communication channels. They are NOT direct LLM primitives.
+ *
+ * For direct LLM primitives, use the identically-named functions from
+ * `ai-functions` instead. See module documentation for comparison table.
+ */
 export { approve } from './approve.js'
 export { ask } from './ask.js'
+export { browse } from './browse.js'
 export { do } from './do.js'
 export { decide } from './decide.js'
 export { generate } from './generate.js'
+export { image } from './image.js'
 export { is } from './is.js'
 export { notify } from './notify.js'
+export { video } from './video.js'
+
 export { kpis, okrs } from './kpis.js'
 
 // Export verb definitions
 export { WorkerVerbs } from './types.js'
 
+// Export capability tiers
+export {
+  CAPABILITY_TIERS,
+  TIER_ORDER,
+  compareTiers,
+  isHigherTier,
+  isLowerTier,
+  getNextTier,
+  getPreviousTier,
+  getTierConfig,
+  getToolsForTier,
+  matchTierToComplexity,
+  canExecuteAtTier,
+  validateTierEscalation,
+  createCapabilityProfile,
+  TierRegistry,
+} from './capability-tiers.js'
+
+export type {
+  CapabilityTier,
+  CapabilityProfile,
+  TierConfig,
+  TierToolset,
+  TaskComplexity,
+  TierMatchResult,
+  TierEscalation,
+  EscalationValidationResult,
+  ProfileConstraints,
+} from './capability-tiers.js'
+
+// Export browser automation types
+export type {
+  BrowseOptions,
+  BrowseResult,
+  BrowseAction,
+  BrowseActionType,
+  Viewport,
+  ClickOptions,
+  TypeOptions,
+  ScrollOptions,
+  ScreenshotOptions,
+  ExtractOptions,
+} from './browse.js'
+
+// Export image generation types
+export type {
+  ImageStyle,
+  ImageSize,
+  ImageFormat,
+  ImageOptions,
+  ImageResult,
+  VariationOptions,
+  EditOptions,
+  UpscaleOptions,
+  UpscaleResult,
+} from './image.js'
+
+// Export video generation types
+export type {
+  VideoOptions,
+  VideoResult,
+  VideoResolution,
+  VideoAspectRatio,
+  VideoModel,
+  VideoStyle,
+  VideoMetadata,
+  VideoFromImageOptions,
+  VideoExtendOptions,
+  VideoEditOptions,
+} from './video.js'
+
 // Export transport bridge (connects to digital-tools)
 export type {
   Transport,
@@ -116,3 +224,303 @@ export {
   MessageTypeMapping,
   CallTypeMapping,
 } from './transports.js'
+
+// Export cascade context for agent coordination
+export {
+  // Functions
+  createCascadeContext,
+  validateContext,
+  enrichContext,
+  serializeContext,
+  deserializeContext,
+  mergeContexts,
+  diffContexts,
+  createContextVersion,
+  // Schemas
+  AgentCascadeContextSchema,
+  AgentTierSchema,
+  ContextVersionSchema,
+  AgentRefSchema,
+  TaskPrioritySchema,
+  TaskInfoSchema,
+  ExecutionPhaseSchema,
+  ExecutionStateSchema,
+  TraceEntrySchema,
+} from './cascade-context.js'
+
+export type {
+  AgentCascadeContext,
+  AgentTier,
+  AgentRef,
+  ContextVersion,
+  ContextEnrichment,
+  ValidationResult,
+  TaskPriority,
+  TaskInfo,
+  ExecutionPhase,
+  ExecutionState,
+  TraceEntry,
+  ContextChange,
+  ContextDiff,
+} from './cascade-context.js'
+
+// Export agent-to-agent communication layer
+export {
+  // Message Bus
+  AgentMessageBus,
+  createMessageBus,
+  // Core Functions
+  sendToAgent,
+  broadcastToGroup,
+  requestFromAgent,
+  onMessage,
+  acknowledge,
+  // Coordination Patterns
+  requestResponse,
+  fanOut,
+  fanIn,
+  pipeline,
+  // Handoff Protocol
+  initiateHandoff,
+  acceptHandoff,
+  rejectHandoff,
+  completeHandoff,
+} from './agent-comms.js'
+
+export type {
+  // Message Types
+  AgentMessage,
+  MessageEnvelope,
+  MessageAck,
+  MessageType,
+  MessagePriority,
+  DeliveryStatus,
+  // Handoff Types
+  HandoffRequest,
+  HandoffResult,
+  HandoffStatus,
+  // Coordination Types
+  CoordinationPattern,
+  // Handler Types
+  MessageHandler,
+  SubscribeOptions,
+  // Options Types
+  MessageBusOptions,
+  SendOptions,
+  RequestOptions,
+  OnMessageOptions,
+  RequestResponseOptions,
+  FanOutOptions,
+  FanOutResult,
+  FanInOptions,
+  PipelineOptions,
+  InitiateHandoffOptions,
+  RejectHandoffOptions,
+  CompleteHandoffOptions,
+} from './agent-comms.js'
+
+// Export load balancing and routing for agent coordination
+export {
+  // Balancer Factories
+  createRoundRobinBalancer,
+  createLeastBusyBalancer,
+  createCapabilityRouter,
+  createPriorityQueueBalancer,
+  createAgentAvailabilityTracker,
+  createCompositeBalancer,
+  createRoutingRuleEngine,
+  // Metrics
+  collectRoutingMetrics,
+  resetRoutingMetrics,
+} from './load-balancing.js'
+
+export type {
+  // Core Types
+  LoadBalancer,
+  BalancerStrategy,
+  AgentInfo,
+  TaskRequest,
+  RouteResult,
+  // Availability Types
+  AgentAvailability,
+  // Rule Types
+  RoutingRule,
+  RoutingRuleCondition,
+  // Metrics Types
+  RoutingMetrics,
+  // Composite Types
+  CompositeBalancerConfig,
+} from './load-balancing.js'
+
+// Export Slack transport adapter
+export {
+  SlackTransport,
+  createSlackTransport,
+  registerSlackTransport,
+  // Block Kit helpers
+  slackSection,
+  slackHeader,
+  slackDivider,
+  slackContext,
+  slackButton,
+  slackActions,
+} from './transports/slack.js'
+
+export type {
+  SlackTransportConfig,
+  SlackBlockType,
+  SlackTextObject,
+  SlackButtonElement,
+  SlackConfirmDialog,
+  SlackSectionBlock,
+  SlackDividerBlock,
+  SlackHeaderBlock,
+  SlackContextBlock,
+  SlackActionsBlock,
+  SlackBlock,
+  SlackMessage,
+  SlackApiResponse,
+  SlackPostMessageResponse,
+  SlackUserInfoResponse,
+  SlackConversationInfoResponse,
+  SlackInteractionPayload,
+  SlackActionPayload,
+  SlackWebhookRequest,
+  WebhookHandlerResult,
+} from './transports/slack.js'
+
+// Export Email transport adapter
+export {
+  EmailTransport,
+  createEmailTransport,
+  createEmailTransportWithProvider,
+  createResendProvider,
+  // Template generators
+  generateNotificationEmail,
+  generateApprovalEmail,
+  // Reply parsing
+  parseApprovalReply,
+  // Type guards
+  isEmailTransportConfig,
+  isApproved,
+  isRejected,
+} from './transports/email.js'
+
+export type {
+  // Provider types
+  EmailProvider,
+  EmailMessage,
+  EmailSendResult,
+  EmailAttachment,
+  EmailTag,
+  // Configuration types
+  EmailTransportConfig,
+  EmailTemplateOptions,
+  // Approval types
+  ApprovalRequestData,
+  ParsedEmailReply,
+  InboundEmail,
+} from './transports/email.js'
+
+// Export error escalation for multi-level error handling
+export {
+  // Error Classification
+  getErrorSeverity,
+  getErrorCategory,
+  createClassifiedError,
+  classifyError,
+  isEscalatable,
+  preserveContext,
+  buildErrorChain,
+  // Escalation Routing
+  createEscalationPolicy,
+  getNextEscalationTier,
+  determineEscalationPath,
+  shouldEscalate,
+  detectCircularEscalation,
+  validateEscalationPath,
+  // Recovery Patterns
+  calculateBackoff,
+  createRetryState,
+  shouldRetry,
+  selectFallbackAgent,
+  getDegradationLevel,
+  createRecoveryState,
+  updateRecoveryState,
+  isRecoverable,
+  // Escalation Engine
+  createEscalationEngine,
+} from './error-escalation.js'
+
+export type {
+  // Error Classification Types
+  ErrorSeverity,
+  ErrorCategory,
+  ClassifiedError,
+  ErrorContext,
+  ErrorChain,
+  SeverityOptions,
+  ErrorChainOptions,
+  // Escalation Routing Types
+  EscalationPath,
+  EscalationPolicy,
+  EscalationPolicyOptions,
+  EscalationRule,
+  EscalationThreshold,
+  EscalationResult,
+  EscalationValidationResult as ErrorEscalationValidationResult,
+  TierPolicyConfig,
+  ErrorHistoryEntry,
+  // Recovery Pattern Types
+  RetryConfig,
+  RetryState,
+  FallbackConfig,
+  AgentForFallback,
+  DegradationLevel,
+  DegradationOptions,
+  RecoveryState,
+  RecoveryStateOptions,
+  RecoveryStateUpdate,
+  // Engine Types
+  EscalationEngine,
+  EscalationEngineOptions,
+  HandleErrorOptions,
+  EscalationMetrics,
+} from './error-escalation.js'
+
+// Export runtime integration for human request processing
+export {
+  // Classes
+  HumanRequestProcessor,
+  InMemoryRequestStore,
+  // Factory functions
+  createHumanRequestProcessor,
+} from './runtime.js'
+
+export type {
+  // Request types
+  HumanRequest,
+  HumanRequestStore,
+  RequestStatus,
+  RequestType,
+  RequestResult,
+  CreateRequestData,
+  UpdateRequestData,
+  // Processor types
+  ProcessorConfig,
+  TransportAdapters,
+  SubmitResult,
+  SubmitRequestData,
+  WebhookPayload,
+  WebhookResult,
+  CompleteCallbackData,
+  TimeoutCallbackData,
+  CancelResult,
+} from './runtime.js'
+
+// Export logger interface for error logging
+export type { Logger } from './logger.js'
+export { noopLogger, createConsoleLogger } from './logger.js'
+
+// Export ID generation utilities
+export { generateRequestId } from './utils/id.js'

package/src/is.ts

@@ -1,5 +1,29 @@
 /**
  * Type validation and checking functionality for digital workers
+ *
+ * IMPORTANT: Schema Validation vs Boolean Assertion
+ * --------------------------------------------------
+ * This module provides comprehensive type/schema validation,
+ * NOT simple boolean assertions.
+ *
+ * - `digital-workers.is()` - Validates values against types or schemas,
+ *   returns detailed validation results with errors and optional coercion.
+ *
+ * - `ai-functions.is()` - Boolean assertion via LLM (e.g., `is\`${x} is valid\``)
+ *   returns true/false based on natural language checking.
+ *
+ * Use digital-workers when you need:
+ * - Type validation with error messages
+ * - Schema validation with field-level errors
+ * - Value coercion (string to number, etc.)
+ * - Structured validation results
+ *
+ * Use ai-functions when you need:
+ * - Natural language boolean checks
+ * - LLM-based semantic validation
+ * - Template literal assertions
+ *
+ * @module
  */
 
 import { generateObject } from 'ai-functions'
@@ -7,26 +31,35 @@ import { schema as convertSchema, type SimpleSchema } from 'ai-functions'
 import type { TypeCheckResult, IsOptions } from './types.js'
 
 /**
- * Check if a value matches an expected type or schema
+ * Validate a value against a type or schema with detailed results.
  *
- * Uses AI-powered validation for complex types and schemas.
- * Can also perform type coercion when enabled.
+ * **Key Difference from ai-functions.is():**
+ * Unlike `ai-functions.is()` which is a boolean assertion using natural
+ * language (e.g., `is\`${email} is valid\`` returns true/false), this
+ * function performs structured type/schema validation and returns a
+ * `TypeCheckResult` with:
+ * - Validation status
+ * - Error messages for invalid fields
+ * - Optionally coerced values
+ *
+ * This is a **validation primitive**, not a boolean assertion primitive.
  *
  * @param value - The value to check
- * @param type - Type name or schema to validate against
- * @param options - Validation options
- * @returns Promise resolving to validation result
+ * @param type - Type name ('email', 'url', 'number') or schema to validate against
+ * @param options - Validation options (coerce, strict)
+ * @returns Promise resolving to TypeCheckResult with valid, value, and errors
  *
  * @example
  * ```ts
- * // Simple type checking
+ * // Simple type checking with result object
  * const result = await is('hello@example.com', 'email')
  * console.log(result.valid) // true
+ * console.log(result.errors) // undefined when valid
  * ```
  *
  * @example
  * ```ts
- * // Schema validation
+ * // Schema validation with detailed errors
  * const result = await is(
  *   { name: 'John', age: 30 },
  *   {
@@ -41,11 +74,13 @@ import type { TypeCheckResult, IsOptions } from './types.js'
  *
  * @example
  * ```ts
- * // With coercion
+ * // With coercion - transforms value to target type
  * const result = await is('123', 'number', { coerce: true })
  * console.log(result.valid) // true
- * console.log(result.value) // 123 (as number)
+ * console.log(result.value) // 123 (as number, not string)
  * ```
+ *
+ * @see {@link ai-functions#is} for natural language boolean assertions
  */
 export async function is(
   value: unknown,
@@ -102,8 +137,7 @@ async function validateSimpleType(
 
     return {
       valid: isValid,
-      value: isValid ? value : undefined,
-      errors: isValid ? undefined : [`Value is not a valid ${type}`],
+      ...(isValid ? { value } : { errors: [`Value is not a valid ${type}`] }),
     }
   }
 
@@ -118,7 +152,11 @@ async function validateSimpleType(
     system: `You are a type validation expert. Determine if a value matches an expected type.
 
 ${coerce ? 'If the value can be coerced to the expected type, provide the coerced value.' : ''}
-${strict ? 'Be strict in your validation - require exact type matches.' : 'Be flexible - allow reasonable type conversions.'}`,
+${
+  strict
+    ? 'Be strict in your validation - require exact type matches.'
+    : 'Be flexible - allow reasonable type conversions.'
+}`,
     prompt: `Validate if this value matches the expected type:
 
 Value: ${JSON.stringify(value)}
@@ -136,7 +174,7 @@ Determine if the value is valid for this type.`,
   return {
     valid: validation.valid,
     value: coerce && validation.coercedValue !== undefined ? validation.coercedValue : value,
-    errors: validation.valid ? undefined : validation.errors,
+    ...(!validation.valid && { errors: validation.errors }),
   }
 }
 
@@ -201,7 +239,7 @@ Check if the value matches the schema structure and types.`,
     return {
       valid: validation.valid,
       value: coerce && validation.coercedValue !== undefined ? validation.coercedValue : value,
-      errors: validation.valid ? undefined : validation.errors,
+      ...(!validation.valid && { errors: validation.errors }),
     }
   }
 }
@@ -209,10 +247,7 @@ Check if the value matches the schema structure and types.`,
 /**
  * Try to coerce a value to a specific type
  */
-function coerceValue(
-  value: unknown,
-  type: string
-): { success: boolean; value?: unknown } {
+function coerceValue(value: unknown, type: string): { success: boolean; value?: unknown } {
   try {
     switch (type) {
       case 'string':
@@ -266,8 +301,7 @@ is.email = async (value: unknown): Promise<TypeCheckResult> => {
 
   return {
     valid,
-    value: valid ? value : undefined,
-    errors: valid ? undefined : ['Invalid email format'],
+    ...(valid ? { value } : { errors: ['Invalid email format'] }),
   }
 }
 
@@ -310,10 +344,11 @@ is.date = async (value: unknown, options: IsOptions = {}): Promise<TypeCheckResu
   const { coerce } = options
 
   if (value instanceof Date) {
+    const isValid = !isNaN(value.getTime())
     return {
-      valid: !isNaN(value.getTime()),
+      valid: isValid,
       value,
-      errors: isNaN(value.getTime()) ? ['Invalid date'] : undefined,
+      ...(!isValid && { errors: ['Invalid date'] }),
     }
   }
 
@@ -360,8 +395,7 @@ is.custom = async (
     const valid = await validator(value)
     return {
       valid,
-      value: valid ? value : undefined,
-      errors: valid ? undefined : ['Custom validation failed'],
+      ...(valid ? { value } : { errors: ['Custom validation failed'] }),
     }
   } catch (error) {
     return {