digital-workers 2.1.3 → 2.4.0

package/src/error-escalation.ts

@@ -424,25 +424,28 @@ export function createClassifiedError(
     original,
     severity: options.severity,
     category: options.category,
-    tier: options.tier,
-    agentId: options.agentId,
-    taskId: options.taskId,
     timestamp: new Date(),
-    stack: original.stack,
-    previousError: options.previousError,
-    context: options.context,
+    ...(original.stack !== undefined && { stack: original.stack }),
+    ...(options.tier !== undefined && { tier: options.tier }),
+    ...(options.agentId !== undefined && { agentId: options.agentId }),
+    ...(options.taskId !== undefined && { taskId: options.taskId }),
+    ...(options.previousError !== undefined && { previousError: options.previousError }),
+    ...(options.context !== undefined && { context: options.context }),
   }
 }
 
 /**
  * Classify an error automatically
  */
-export function classifyError(error: Error, options: Partial<{
-  tier: CapabilityTier
-  agentId: string
-  taskId: string
-  context: ErrorContext
-}> = {}): ClassifiedError {
+export function classifyError(
+  error: Error,
+  options: Partial<{
+    tier: CapabilityTier
+    agentId: string
+    taskId: string
+    context: ErrorContext
+  }> = {}
+): ClassifiedError {
   const severity = getErrorSeverity(error)
   const category = getErrorCategory(error)
 
@@ -531,9 +534,11 @@ export function createEscalationPolicy(options: EscalationPolicyOptions): Escala
   return {
     maxEscalationDepth: options.maxEscalationDepth ?? 10,
     allowSkipTiers: options.allowSkipTiers ?? false,
-    skipTierThreshold: options.skipTierThreshold,
+    ...(options.skipTierThreshold !== undefined && {
+      skipTierThreshold: options.skipTierThreshold,
+    }),
     rules: options.rules ?? [],
-    tierPolicies: options.tierPolicies,
+    ...(options.tierPolicies !== undefined && { tierPolicies: options.tierPolicies }),
   }
 }
 
@@ -548,7 +553,7 @@ export function getNextEscalationTier(
 
   // Check custom rules first
   const applicableRules = policy.rules
-    .filter(rule => rule.fromTier === currentTier && rule.condition(error))
+    .filter((rule) => rule.fromTier === currentTier && rule.condition(error))
     .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
 
   if (applicableRules.length > 0) {
@@ -608,17 +613,13 @@ export function shouldEscalate(
   // Filter by time window if specified
   let relevantErrors = errorHistory
   if (timeWindow) {
-    relevantErrors = errorHistory.filter(
-      entry => now - entry.timestamp <= timeWindow
-    )
+    relevantErrors = errorHistory.filter((entry) => now - entry.timestamp <= timeWindow)
   }
 
   // Calculate weighted count if severity multiplier is specified
   if (severityMultiplier) {
     const weightedCount = relevantErrors.reduce((sum, entry) => {
-      const multiplier = entry.severity
-        ? (severityMultiplier[entry.severity] ?? 1)
-        : 1
+      const multiplier = entry.severity ? severityMultiplier[entry.severity] ?? 1 : 1
       return sum + multiplier
     }, 0)
     return weightedCount >= errorCount
@@ -630,10 +631,7 @@ export function shouldEscalate(
 /**
  * Detect circular escalation
  */
-export function detectCircularEscalation(
-  path: EscalationPath,
-  history: CapabilityTier[]
-): boolean {
+export function detectCircularEscalation(path: EscalationPath, history: CapabilityTier[]): boolean {
   // If we're going back to a tier we've already visited, it's circular
   if (history.includes(path.toTier)) {
     return true
@@ -642,7 +640,7 @@ export function detectCircularEscalation(
   // Check for de-escalation (going to a lower tier)
   if (TIER_ORDER[path.toTier] < TIER_ORDER[path.fromTier]) {
     // If we've already been at a tier higher than where we're going, it's circular
-    const maxTierVisited = Math.max(...history.map(t => TIER_ORDER[t]))
+    const maxTierVisited = Math.max(...history.map((t) => TIER_ORDER[t]))
     if (TIER_ORDER[path.toTier] < maxTierVisited) {
       return true
     }
@@ -686,12 +684,7 @@ export function validateEscalationPath(
  * Calculate backoff delay with optional jitter
  */
 export function calculateBackoff(config: RetryConfig, attemptNumber: number): number {
-  const {
-    baseDelayMs,
-    maxDelayMs = Infinity,
-    backoffMultiplier = 2,
-    jitterPercent = 0,
-  } = config
+  const { baseDelayMs, maxDelayMs = Infinity, backoffMultiplier = 2, jitterPercent = 0 } = config
 
   // Calculate exponential delay
   let delay = baseDelayMs * Math.pow(backoffMultiplier, attemptNumber)
@@ -757,9 +750,7 @@ export function selectFallbackAgent(
   agents: AgentForFallback[]
 ): AgentForFallback | null {
   // Filter excluded agents
-  let candidates = agents.filter(
-    a => !config.excludeAgentIds?.includes(a.id)
-  )
+  let candidates = agents.filter((a) => !config.excludeAgentIds?.includes(a.id))
 
   if (candidates.length === 0) {
     return null
@@ -768,9 +759,9 @@ export function selectFallbackAgent(
   switch (config.strategy) {
     case 'capability-match':
       if (config.requiredSkills && config.requiredSkills.length > 0) {
-        candidates = candidates.filter(a => {
+        candidates = candidates.filter((a) => {
           const agentSkills = a.skills ?? []
-          return config.requiredSkills!.every(skill => agentSkills.includes(skill))
+          return config.requiredSkills!.every((skill) => agentSkills.includes(skill))
         })
       }
       return candidates[0] ?? null
@@ -785,7 +776,7 @@ export function selectFallbackAgent(
 
     case 'same-tier':
       if (config.currentTier) {
-        candidates = candidates.filter(a => a.tier === config.currentTier)
+        candidates = candidates.filter((a) => a.tier === config.currentTier)
       }
       return candidates[0] ?? null
 
@@ -849,7 +840,7 @@ export function createRecoveryState(options: RecoveryStateOptions): RecoveryStat
   return {
     errorId: options.errorId,
     tier: options.tier,
-    agentId: options.agentId,
+    ...(options.agentId !== undefined && { agentId: options.agentId }),
     retryState: createRetryState(),
     escalated: false,
     resolved: false,
@@ -886,14 +877,14 @@ export function updateRecoveryState(
         escalated: true,
         escalationPath: [...state.escalationPath, newTier],
         lastAction: 'escalate',
-        isTerminal: update.isTerminal,
+        ...(update.isTerminal !== undefined && { isTerminal: update.isTerminal }),
       }
 
     case 'fallback':
       const oldAgentId = state.agentId
       return {
         ...state,
-        agentId: update.toAgentId,
+        ...(update.toAgentId !== undefined && { agentId: update.toAgentId }),
         fallbackHistory: oldAgentId
           ? [...state.fallbackHistory, oldAgentId]
           : state.fallbackHistory,
@@ -904,7 +895,7 @@ export function updateRecoveryState(
       return {
         ...state,
         resolved: true,
-        resolution: update.resolution,
+        ...(update.resolution !== undefined && { resolution: update.resolution }),
         lastAction: 'resolve',
       }
 
@@ -967,10 +958,7 @@ export function createEscalationEngine(options: EscalationEngineOptions = {}): E
     retriesSuccessful: 0,
   }
 
-  async function handleError(
-    error: Error,
-    opts: HandleErrorOptions
-  ): Promise<EscalationResult> {
+  async function handleError(error: Error, opts: HandleErrorOptions): Promise<EscalationResult> {
     // Classify the error
     const severity = opts.severity ?? getErrorSeverity(error)
     const category = getErrorCategory(error)
@@ -978,11 +966,11 @@ export function createEscalationEngine(options: EscalationEngineOptions = {}): E
     const classifiedError = createClassifiedError(error, {
       severity,
       category,
-      tier: opts.tier,
-      agentId: opts.agentId,
-      taskId: opts.taskId,
-      previousError: opts.previousError,
-      context: opts.context,
+      ...(opts.tier !== undefined && { tier: opts.tier }),
+      ...(opts.agentId !== undefined && { agentId: opts.agentId }),
+      ...(opts.taskId !== undefined && { taskId: opts.taskId }),
+      ...(opts.previousError !== undefined && { previousError: opts.previousError }),
+      ...(opts.context !== undefined && { context: opts.context }),
     })
 
     // Update metrics
@@ -1036,10 +1024,11 @@ export function createEscalationEngine(options: EscalationEngineOptions = {}): E
       } else if (opts.availableAgents && opts.availableAgents.length > 0) {
         // Try fallback
         action = 'fallback'
-        fallbackAgent = selectFallbackAgent(
-          { strategy: 'capability-match', excludeAgentIds: [opts.agentId ?? ''] },
-          opts.availableAgents
-        ) ?? undefined
+        fallbackAgent =
+          selectFallbackAgent(
+            { strategy: 'capability-match', excludeAgentIds: [opts.agentId ?? ''] },
+            opts.availableAgents
+          ) ?? undefined
       } else {
         action = 'degrade'
         degradationLevel = getDegradationLevel(severity)
@@ -1049,10 +1038,11 @@ export function createEscalationEngine(options: EscalationEngineOptions = {}): E
     else {
       if (opts.availableAgents && opts.availableAgents.length > 0) {
         action = 'fallback'
-        fallbackAgent = selectFallbackAgent(
-          { strategy: 'same-tier', currentTier: 'human', excludeAgentIds: [opts.agentId ?? ''] },
-          opts.availableAgents
-        ) ?? undefined
+        fallbackAgent =
+          selectFallbackAgent(
+            { strategy: 'same-tier', currentTier: 'human', excludeAgentIds: [opts.agentId ?? ''] },
+            opts.availableAgents
+          ) ?? undefined
         if (!fallbackAgent) {
           action = 'terminal'
         }
@@ -1065,14 +1055,12 @@ export function createEscalationEngine(options: EscalationEngineOptions = {}): E
       handled: true,
       action,
       classifiedError,
-      retryDelay,
-      escalationPath,
-      fallbackAgent,
-      degradationLevel,
-      preservedContext: opts.context,
-      errorChain: opts.previousError
-        ? buildErrorChain(classifiedError)
-        : undefined,
+      ...(retryDelay !== undefined && { retryDelay }),
+      ...(escalationPath !== undefined && { escalationPath }),
+      ...(fallbackAgent !== undefined && { fallbackAgent }),
+      ...(degradationLevel !== undefined && { degradationLevel }),
+      ...(opts.context !== undefined && { preservedContext: opts.context }),
+      ...(opts.previousError !== undefined && { errorChain: buildErrorChain(classifiedError) }),
     }
   }
 

package/src/generate.ts

@@ -1,5 +1,34 @@
 /**
  * Content generation functionality for digital workers
+ *
+ * IMPORTANT: Worker-Context Generation vs Direct LLM Generation
+ * --------------------------------------------------------------
+ * This module provides content generation within a worker context,
+ * with rich metadata about the generation process.
+ *
+ * - `digital-workers.generate()` - Generates content with full metadata
+ *   (tokens used, duration, model info) and supports multiple content types
+ *   including text, code, structured, image, video, and audio.
+ *
+ * - `ai-functions.generate()` - Core generation primitive that powers all
+ *   ai-functions; lower-level function with type-based dispatch.
+ *
+ * The key difference is context and metadata:
+ * - digital-workers returns `GenerateResult<T>` with content + metadata
+ * - ai-functions returns just the generated content
+ *
+ * Use digital-workers when you need:
+ * - Rich metadata about generation (tokens, duration, model)
+ * - Content type variants (text, code, structured, media)
+ * - Tone, audience, and length modifiers
+ * - Iterative refinement workflows
+ *
+ * Use ai-functions when you need:
+ * - Direct LLM generation without metadata
+ * - Template literal syntax (`ai\`prompt\``)
+ * - Promise pipelining and schema inference
+ *
+ * @module
  */
 
 import { generateObject, generateText } from 'ai-functions'
@@ -7,23 +36,31 @@ import type { SimpleSchema } from 'ai-functions'
 import type { GenerateResult, GenerateOptions } from './types.js'
 
 /**
- * Generate content
+ * Generate content with rich metadata and multiple content type support.
  *
- * Uses AI to generate various types of content including text,
- * code, structured data, images, video, and audio.
+ * **Key Difference from ai-functions.generate():**
+ * Unlike `ai-functions.generate()` which is a lower-level type-dispatch
+ * function, this function returns a `GenerateResult` wrapper with:
+ * - The generated content
+ * - Generation metadata (model, tokens, duration)
+ * - Content type information
+ *
+ * This provides better observability for worker-based content generation.
  *
  * @param prompt - What to generate
- * @param options - Generation options
- * @returns Promise resolving to generated content
+ * @param options - Generation options (type, schema, instructions, model)
+ * @returns Promise resolving to GenerateResult with content and metadata
  *
  * @example
  * ```ts
- * // Generate text content
+ * // Generate text content with metadata
  * const result = await generate('Write a product description for wireless earbuds', {
  *   type: 'text',
  *   instructions: 'Focus on sound quality and battery life. Keep it under 100 words.',
  * })
- * console.log(result.content)
+ * console.log(result.content) // The generated text
+ * console.log(result.metadata.tokens) // Tokens used
+ * console.log(result.metadata.duration) // Generation time in ms
  * ```
  *
  * @example
@@ -52,18 +89,17 @@ import type { GenerateResult, GenerateOptions } from './types.js'
  *   instructions: 'Use TypeScript and hooks. Include prop types.',
  * })
  * console.log(result.content) // TypeScript React component code
+ * console.log(result.metadata.language) // 'typescript'
  * ```
+ *
+ * @see {@link ai-functions#generate} for lower-level type-dispatch generation
+ * @see {@link ai-functions#ai} for template literal generation syntax
  */
 export async function generate<T = string>(
   prompt: string,
   options: GenerateOptions = {}
 ): Promise<GenerateResult<T>> {
-  const {
-    type = 'text',
-    schema,
-    instructions,
-    model = 'sonnet',
-  } = options
+  const { type = 'text', schema, instructions, model = 'sonnet' } = options
 
   const startTime = Date.now()
 
@@ -111,7 +147,7 @@ export async function generate<T = string>(
         type: 'structured',
         metadata: {
           model,
-          tokens: result.usage?.totalTokens,
+          tokens: (result.usage as { totalTokens?: number } | undefined)?.totalTokens,
           duration: Date.now() - startTime,
         },
       }
@@ -144,7 +180,7 @@ export async function generate<T = string>(
         type: 'code',
         metadata: {
           model,
-          tokens: result.usage?.totalTokens,
+          tokens: (result.usage as { totalTokens?: number } | undefined)?.totalTokens,
           duration: Date.now() - startTime,
           language: codeResult.language,
           explanation: codeResult.explanation,
@@ -199,9 +235,7 @@ generate.variations = async <T = string>(
   count: number,
   options: GenerateOptions = {}
 ): Promise<Array<GenerateResult<T>>> => {
-  return Promise.all(
-    Array.from({ length: count }, () => generate<T>(prompt, options))
-  )
+  return Promise.all(Array.from({ length: count }, () => generate<T>(prompt, options)))
 }
 
 /**

package/src/goals.ts

@@ -2,7 +2,10 @@
  * Goals definition for digital workers
  */
 
-import type { WorkerGoals, KPI } from './types.js'
+import { calculateProgress, isOnTrack } from 'org.ai'
+import type { WorkerGoals, WorkerKPI } from './types.js'
+
+// Note: Goal, Goals types are re-exported from types.ts which imports from org.ai
 
 /**
  * Define worker goals
@@ -15,7 +18,7 @@ import type { WorkerGoals, KPI } from './types.js'
  *
  * @example
  * ```ts
- * const engineeringGoals = Goals({
+ * const engineeringGoals = defineGoals({
  *   shortTerm: [
  *     'Complete Q1 roadmap features',
  *     'Reduce bug backlog by 30%',
@@ -55,7 +58,7 @@ import type { WorkerGoals, KPI } from './types.js'
  *
  * @example
  * ```ts
- * const supportGoals = Goals({
+ * const supportGoals = defineGoals({
  *   shortTerm: [
  *     'Achieve 95% customer satisfaction',
  *     'Reduce average response time to < 5 min',
@@ -78,7 +81,7 @@ import type { WorkerGoals, KPI } from './types.js'
  * })
  * ```
  */
-export function Goals(definition: WorkerGoals): WorkerGoals {
+export function defineGoals(definition: WorkerGoals): WorkerGoals {
   return definition
 }
 
@@ -91,10 +94,10 @@ export function Goals(definition: WorkerGoals): WorkerGoals {
  *
  * @example
  * ```ts
- * const updated = Goals.addShortTerm(engineeringGoals, 'Complete security audit')
+ * const updated = defineGoals.addShortTerm(engineeringGoals, 'Complete security audit')
  * ```
  */
-Goals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+defineGoals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
   ...goals,
   shortTerm: [...goals.shortTerm, goal],
 })
@@ -108,10 +111,10 @@ Goals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.addLongTerm(engineeringGoals, 'Build ML platform')
+ * const updated = defineGoals.addLongTerm(engineeringGoals, 'Build ML platform')
  * ```
  */
-Goals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+defineGoals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
   ...goals,
   longTerm: [...goals.longTerm, goal],
 })
@@ -125,10 +128,10 @@ Goals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.addStrategic(engineeringGoals, 'Become carbon neutral')
+ * const updated = defineGoals.addStrategic(engineeringGoals, 'Become carbon neutral')
  * ```
  */
-Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+defineGoals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
   ...goals,
   strategic: [...(goals.strategic || []), goal],
 })
@@ -142,7 +145,7 @@ Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.addMetric(engineeringGoals, {
+ * const updated = defineGoals.addMetric(engineeringGoals, {
  *   name: 'Code Quality',
  *   description: 'Code quality score from SonarQube',
  *   current: 85,
@@ -153,7 +156,7 @@ Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  * })
  * ```
  */
-Goals.addMetric = (goals: WorkerGoals, kpi: KPI): WorkerGoals => ({
+defineGoals.addMetric = (goals: WorkerGoals, kpi: WorkerKPI): WorkerGoals => ({
   ...goals,
   metrics: [...(goals.metrics || []), kpi],
 })
@@ -168,22 +171,26 @@ Goals.addMetric = (goals: WorkerGoals, kpi: KPI): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.updateMetric(engineeringGoals, 'Deployment Frequency', {
+ * const updated = defineGoals.updateMetric(engineeringGoals, 'Deployment Frequency', {
  *   current: 8,
  *   trend: 'up',
  * })
  * ```
  */
-Goals.updateMetric = (
+defineGoals.updateMetric = (
   goals: WorkerGoals,
   name: string,
-  updates: Partial<Omit<KPI, 'name'>>
-): WorkerGoals => ({
-  ...goals,
-  metrics: goals.metrics?.map((kpi) =>
+  updates: Partial<Omit<WorkerKPI, 'name'>>
+): WorkerGoals => {
+  const updatedMetrics = goals.metrics?.map((kpi) =>
     kpi.name === name ? { ...kpi, ...updates } : kpi
-  ),
-})
+  )
+  const result: WorkerGoals = { ...goals }
+  if (updatedMetrics) {
+    result.metrics = updatedMetrics
+  }
+  return result
+}
 
 /**
  * Get progress for a KPI (0-1)
@@ -194,12 +201,11 @@ Goals.updateMetric = (
  * @example
  * ```ts
  * const kpi = { current: 75, target: 100 }
- * const progress = Goals.progress(kpi) // 0.75
+ * const progress = defineGoals.progress(kpi) // 0.75
  * ```
  */
-Goals.progress = (kpi: Pick<KPI, 'current' | 'target'>): number => {
-  if (kpi.target === 0) return 0
-  return Math.min(1, Math.max(0, kpi.current / kpi.target))
+defineGoals.progress = (kpi: Pick<WorkerKPI, 'current' | 'target'>): number => {
+  return calculateProgress(kpi)
 }
 
 /**
@@ -212,9 +218,12 @@ Goals.progress = (kpi: Pick<KPI, 'current' | 'target'>): number => {
  * @example
  * ```ts
  * const kpi = { current: 85, target: 100 }
- * const onTrack = Goals.onTrack(kpi) // true (85% >= 80% threshold)
+ * const onTrack = defineGoals.onTrack(kpi) // true (85% >= 80% threshold)
  * ```
  */
-Goals.onTrack = (kpi: Pick<KPI, 'current' | 'target'>, threshold = 0.8): boolean => {
-  return Goals.progress(kpi) >= threshold
+defineGoals.onTrack = (kpi: Pick<WorkerKPI, 'current' | 'target'>, threshold = 0.8): boolean => {
+  return isOnTrack(kpi, threshold)
 }
+
+// Legacy alias for backward compatibility
+export { defineGoals as Goals }