digital-workers 2.1.3 → 2.4.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,13 +95,27 @@ 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
@@ -114,6 +151,47 @@ export type {
   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,
@@ -274,6 +352,76 @@ export type {
   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
@@ -339,3 +487,40 @@ export type {
   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 {

package/src/kpis.ts

@@ -2,11 +2,20 @@
  * KPI and OKR tracking functionality for digital workers
  */
 
-import type { KPI, OKR } from './types.js'
+import type { KPI, OKR, KeyResult } from 'org.ai'
+import { calculateProgress, isOnTrack, calculateGap } from 'org.ai'
+import type { WorkerKPI, WorkerOKR } from './types.js'
+
+// Re-export KPI, OKR from org.ai for convenience
+export type { KPI, OKR, KeyResult } from 'org.ai'
 
 /**
  * Define and track Key Performance Indicators
  *
+ * Uses WorkerKPI which has a simpler interface with `current` and `target`
+ * as required number fields. For the full org.ai KPI with `id`, `value`,
+ * `category`, and `history`, use the KPI type directly.
+ *
  * @param definition - KPI definition or array of KPIs
  * @returns The defined KPI(s)
  *
@@ -46,9 +55,9 @@ import type { KPI, OKR } from './types.js'
  * ])
  * ```
  */
-export function kpis(definition: KPI): KPI
-export function kpis(definition: KPI[]): KPI[]
-export function kpis(definition: KPI | KPI[]): KPI | KPI[] {
+export function kpis(definition: WorkerKPI): WorkerKPI
+export function kpis(definition: WorkerKPI[]): WorkerKPI[]
+export function kpis(definition: WorkerKPI | WorkerKPI[]): WorkerKPI | WorkerKPI[] {
   return definition
 }
 
@@ -66,9 +75,9 @@ export function kpis(definition: KPI | KPI[]): KPI | KPI[] {
  * console.log(updated.trend) // 'up' (automatically determined)
  * ```
  */
-kpis.update = (kpi: KPI, current: number): KPI => {
+kpis.update = (kpi: WorkerKPI, current: number): WorkerKPI => {
   // Determine trend
-  let trend: KPI['trend'] = 'stable'
+  let trend: WorkerKPI['trend'] = 'stable'
   if (current > kpi.current) {
     trend = 'up'
   } else if (current < kpi.current) {
@@ -94,9 +103,8 @@ kpis.update = (kpi: KPI, current: number): KPI => {
  * const progress = kpis.progress(kpi) // 0.75
  * ```
  */
-kpis.progress = (kpi: Pick<KPI, 'current' | 'target'>): number => {
-  if (kpi.target === 0) return 0
-  return Math.min(1, Math.max(0, kpi.current / kpi.target))
+kpis.progress = (kpi: Pick<WorkerKPI, 'current' | 'target'>): number => {
+  return calculateProgress(kpi)
 }
 
 /**
@@ -112,8 +120,8 @@ kpis.progress = (kpi: Pick<KPI, 'current' | 'target'>): number => {
  * const onTrack = kpis.onTrack(kpi) // true (85% >= 80%)
  * ```
  */
-kpis.onTrack = (kpi: Pick<KPI, 'current' | 'target'>, threshold = 0.8): boolean => {
-  return kpis.progress(kpi) >= threshold
+kpis.onTrack = (kpi: Pick<WorkerKPI, 'current' | 'target'>, threshold = 0.8): boolean => {
+  return isOnTrack(kpi, threshold)
 }
 
 /**
@@ -128,8 +136,8 @@ kpis.onTrack = (kpi: Pick<KPI, 'current' | 'target'>, threshold = 0.8): boolean
  * const gap = kpis.gap(kpi) // 25
  * ```
  */
-kpis.gap = (kpi: Pick<KPI, 'current' | 'target'>): number => {
-  return kpi.target - kpi.current
+kpis.gap = (kpi: Pick<WorkerKPI, 'current' | 'target'>): number => {
+  return calculateGap(kpi)
 }
 
 /**
@@ -151,7 +159,7 @@ kpis.gap = (kpi: Pick<KPI, 'current' | 'target'>): number => {
  * // "Deployment Frequency: 5/10 deploys/week (50%, trending up)"
  * ```
  */
-kpis.format = (kpi: KPI): string => {
+kpis.format = (kpi: WorkerKPI): string => {
   const progress = kpis.progress(kpi)
   const progressPercent = Math.round(progress * 100)
   const trendEmoji = kpi.trend === 'up' ? '↑' : kpi.trend === 'down' ? '↓' : '→'
@@ -175,17 +183,15 @@ kpis.format = (kpi: KPI): string => {
  * ```
  */
 kpis.compare = (
-  previous: Pick<KPI, 'current' | 'target'>,
-  current: Pick<KPI, 'current' | 'target'>
+  previous: Pick<WorkerKPI, 'current' | 'target'>,
+  current: Pick<WorkerKPI, 'current' | 'target'>
 ): {
   delta: number
   percentChange: number
   improved: boolean
 } => {
   const delta = current.current - previous.current
-  const percentChange = previous.current !== 0
-    ? (delta / previous.current) * 100
-    : 0
+  const percentChange = previous.current !== 0 ? (delta / previous.current) * 100 : 0
 
   // Improved if we got closer to the target
   const previousGap = Math.abs(previous.target - previous.current)
@@ -202,6 +208,10 @@ kpis.compare = (
 /**
  * Define OKRs (Objectives and Key Results)
  *
+ * Uses WorkerOKR which has WorkerRef for owner.
+ * For the full org.ai OKR with `id`, `status`, `period`, etc.,
+ * use the OKR type directly.
+ *
  * @param definition - OKR definition
  * @returns The defined OKR
  *
@@ -229,12 +239,12 @@ kpis.compare = (
  *       unit: '%',
  *     },
  *   ],
- *   owner: 'engineering-team',
+ *   owner: { id: 'engineering-team', type: 'agent' },
  *   dueDate: new Date('2024-03-31'),
  * })
  * ```
  */
-export function okrs(definition: OKR): OKR {
+export function okrs(definition: WorkerOKR): WorkerOKR {
   return definition
 }
 
@@ -250,7 +260,7 @@ export function okrs(definition: OKR): OKR {
  * console.log(progress) // 0.67 (67% complete)
  * ```
  */
-okrs.progress = (okr: OKR): number => {
+okrs.progress = (okr: WorkerOKR): number => {
   if (okr.keyResults.length === 0) return 0
 
   const totalProgress = okr.keyResults.reduce((sum, kr) => {
@@ -277,17 +287,11 @@ okrs.progress = (okr: OKR): number => {
  * )
  * ```
  */
-okrs.updateKeyResult = (
-  okr: OKR,
-  keyResultName: string,
-  current: number
-): OKR => {
+okrs.updateKeyResult = (okr: WorkerOKR, keyResultName: string, current: number): WorkerOKR => {
+  const { progress: _progress, ...rest } = okr
   return {
-    ...okr,
-    keyResults: okr.keyResults.map((kr) =>
-      kr.name === keyResultName ? { ...kr, current } : kr
-    ),
-    progress: undefined, // Will be recalculated
+    ...rest,
+    keyResults: okr.keyResults.map((kr) => (kr.name === keyResultName ? { ...kr, current } : kr)),
   }
 }
 
@@ -303,7 +307,7 @@ okrs.updateKeyResult = (
  * const onTrack = okrs.onTrack(engineeringOKR)
  * ```
  */
-okrs.onTrack = (okr: OKR, threshold = 0.7): boolean => {
+okrs.onTrack = (okr: WorkerOKR, threshold = 0.7): boolean => {
   return okrs.progress(okr) >= threshold
 }
 
@@ -323,7 +327,7 @@ okrs.onTrack = (okr: OKR, threshold = 0.7): boolean => {
  * // • Change Failure Rate: 15/5 % (300%)
  * ```
  */
-okrs.format = (okr: OKR): string => {
+okrs.format = (okr: WorkerOKR): string => {
   const progress = okrs.progress(okr)
   const progressPercent = Math.round(progress * 100)
 
@@ -332,12 +336,13 @@ okrs.format = (okr: OKR): string => {
     ...okr.keyResults.map((kr) => {
       const krProgress = kpis.progress(kr)
       const krPercent = Math.round(krProgress * 100)
-      return `  • ${kr.name}: ${kr.current}/${kr.target} ${kr.unit} (${krPercent}%)`
+      return `  - ${kr.name}: ${kr.current}/${kr.target} ${kr.unit} (${krPercent}%)`
     }),
   ]
 
   if (okr.owner) {
-    lines.push(`  Owner: ${okr.owner}`)
+    const ownerDisplay = typeof okr.owner === 'string' ? okr.owner : okr.owner.id
+    lines.push(`  Owner: ${ownerDisplay}`)
   }
 
   if (okr.dueDate) {