digital-workers 0.1.1 → 2.0.1

package/src/decide.ts

@@ -0,0 +1,295 @@
+/**
+ * Decision-making functionality for digital workers
+ */
+
+import { generateObject } from 'ai-functions'
+import type { Decision, DecideOptions } from './types.js'
+
+/**
+ * Make a decision from a set of options
+ *
+ * Uses AI to evaluate options and make a reasoned decision,
+ * or can route to human decision-makers for critical choices.
+ *
+ * @param options - Decision options with configuration
+ * @returns Promise resolving to decision result
+ *
+ * @example
+ * ```ts
+ * const decision = await decide({
+ *   options: ['Option A', 'Option B', 'Option C'],
+ *   context: 'We need to choose a technology stack for our new project',
+ *   criteria: [
+ *     'Developer experience',
+ *     'Performance',
+ *     'Community support',
+ *     'Long-term viability',
+ *   ],
+ * })
+ *
+ * console.log(`Decision: ${decision.choice}`)
+ * console.log(`Reasoning: ${decision.reasoning}`)
+ * console.log(`Confidence: ${decision.confidence}`)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Complex decision with structured options
+ * const decision = await decide({
+ *   options: [
+ *     { id: 'migrate', label: 'Migrate to new platform' },
+ *     { id: 'refactor', label: 'Refactor existing system' },
+ *     { id: 'rebuild', label: 'Rebuild from scratch' },
+ *   ],
+ *   context: {
+ *     budget: '$500k',
+ *     timeline: '6 months',
+ *     teamSize: 5,
+ *     currentSystem: 'Legacy monolith',
+ *   },
+ *   criteria: ['Cost', 'Time to market', 'Risk', 'Scalability'],
+ * })
+ * ```
+ */
+export async function decide<T = string>(
+  options: DecideOptions<T>
+): Promise<Decision<T>> {
+  const {
+    options: choices,
+    context,
+    criteria = [],
+    includeReasoning = true,
+  } = options
+
+  // Format context for the prompt
+  const contextStr = typeof context === 'string'
+    ? context
+    : context
+    ? JSON.stringify(context, null, 2)
+    : 'No additional context provided'
+
+  // Format choices for the prompt
+  const choicesStr = choices
+    .map((choice, i) => {
+      if (typeof choice === 'object' && choice !== null) {
+        return `${i + 1}. ${JSON.stringify(choice)}`
+      }
+      return `${i + 1}. ${choice}`
+    })
+    .join('\n')
+
+  const result = await generateObject({
+    model: 'sonnet',
+    schema: {
+      choice: 'The chosen option (must be one of the provided options)',
+      reasoning: includeReasoning
+        ? 'Detailed reasoning explaining why this choice is best'
+        : 'Brief explanation of the choice',
+      confidence: 'Confidence level in this decision as a decimal (number)',
+      alternatives: [
+        {
+          option: 'An alternative option that was considered',
+          score: 'Score for this alternative from 0-100 (number)',
+        },
+      ],
+      criteriaScores: criteria.length > 0
+        ? 'Scores for each criterion as object mapping criterion name to score (0-100)'
+        : undefined,
+    },
+    system: `You are a decision-making expert. Analyze the options carefully and make the best choice based on the context and criteria provided.
+
+${criteria.length > 0 ? `Evaluation Criteria:\n${criteria.map((c, i) => `${i + 1}. ${c}`).join('\n')}` : ''}`,
+    prompt: `Make a decision based on the following:
+
+Context:
+${contextStr}
+
+Options:
+${choicesStr}
+
+${criteria.length > 0 ? `\nEvaluate each option against these criteria:\n${criteria.join(', ')}` : ''}
+
+Provide your decision with clear reasoning.`,
+  })
+
+  const response = result.object as unknown as {
+    choice: T
+    reasoning: string
+    confidence: number
+    alternatives: Array<{ option: T; score: number }>
+    criteriaScores?: Record<string, number>
+  }
+
+  return {
+    choice: response.choice,
+    reasoning: response.reasoning,
+    confidence: Math.min(1, Math.max(0, response.confidence)),
+    alternatives: response.alternatives,
+  }
+}
+
+/**
+ * Make a binary (yes/no) decision
+ *
+ * @param question - The yes/no question
+ * @param context - Context for the decision
+ * @returns Promise resolving to decision
+ *
+ * @example
+ * ```ts
+ * const decision = await decide.yesNo(
+ *   'Should we proceed with the deployment?',
+ *   {
+ *     tests: 'All passing',
+ *     codeReview: 'Approved',
+ *     loadTests: 'Within acceptable range',
+ *   }
+ * )
+ *
+ * if (decision.choice === 'yes') {
+ *   // Proceed with deployment
+ * }
+ * ```
+ */
+decide.yesNo = async (
+  question: string,
+  context?: string | Record<string, unknown>
+): Promise<Decision<'yes' | 'no'>> => {
+  return decide({
+    options: ['yes', 'no'] as const,
+    context: typeof context === 'string'
+      ? `${question}\n\n${context}`
+      : `${question}\n\n${context ? JSON.stringify(context, null, 2) : ''}`,
+  })
+}
+
+/**
+ * Make a prioritization decision
+ *
+ * Ranks options by priority instead of choosing one.
+ *
+ * @param items - Items to prioritize
+ * @param context - Context for prioritization
+ * @param criteria - Criteria for prioritization
+ * @returns Promise resolving to prioritized list
+ *
+ * @example
+ * ```ts
+ * const prioritized = await decide.prioritize(
+ *   ['Feature A', 'Bug fix B', 'Tech debt C', 'Feature D'],
+ *   'Sprint planning for next 2 weeks',
+ *   ['User impact', 'Urgency', 'Effort required']
+ * )
+ *
+ * console.log('Priority order:', prioritized.map(p => p.choice))
+ * ```
+ */
+decide.prioritize = async <T = string>(
+  items: T[],
+  context?: string | Record<string, unknown>,
+  criteria: string[] = []
+): Promise<Array<Decision<T> & { rank: number }>> => {
+  const contextStr = typeof context === 'string'
+    ? context
+    : context
+    ? JSON.stringify(context, null, 2)
+    : 'No additional context provided'
+
+  const itemsStr = items
+    .map((item, i) => `${i + 1}. ${typeof item === 'object' ? JSON.stringify(item) : item}`)
+    .join('\n')
+
+  const result = await generateObject({
+    model: 'sonnet',
+    schema: {
+      prioritized: [
+        {
+          item: 'The item',
+          rank: 'Priority rank (1 = highest) (number)',
+          reasoning: 'Why this priority',
+          confidence: 'Confidence in this ranking (number)',
+        },
+      ],
+    },
+    system: `You are a prioritization expert. Rank items by priority based on the context and criteria.
+
+${criteria.length > 0 ? `Prioritization Criteria:\n${criteria.map((c, i) => `${i + 1}. ${c}`).join('\n')}` : ''}`,
+    prompt: `Prioritize the following items:
+
+Context:
+${contextStr}
+
+Items:
+${itemsStr}
+
+${criteria.length > 0 ? `\nConsider these criteria when prioritizing:\n${criteria.join(', ')}` : ''}
+
+Rank all items from highest to lowest priority.`,
+  })
+
+  const response = result.object as unknown as {
+    prioritized: Array<{
+      item: T
+      rank: number
+      reasoning: string
+      confidence: number
+    }>
+  }
+
+  return response.prioritized.map((p) => ({
+    choice: p.item,
+    rank: p.rank,
+    reasoning: p.reasoning,
+    confidence: Math.min(1, Math.max(0, p.confidence)),
+  }))
+}
+
+/**
+ * Make a decision with approval required
+ *
+ * Makes a recommendation but requires human approval before finalizing.
+ *
+ * @param options - Decision options
+ * @param approver - Who should approve the decision
+ * @returns Promise resolving to approved decision
+ *
+ * @example
+ * ```ts
+ * const decision = await decide.withApproval(
+ *   {
+ *     options: ['Rollback', 'Fix forward', 'Wait'],
+ *     context: 'Production incident - 500 errors on checkout',
+ *     criteria: ['User impact', 'Recovery time', 'Risk'],
+ *   },
+ *   'oncall-engineer@company.com'
+ * )
+ * ```
+ */
+decide.withApproval = async <T = string>(
+  options: DecideOptions<T>,
+  approver: string
+): Promise<Decision<T> & { approved: boolean; approvedBy?: string }> => {
+  // First, make the decision
+  const decision = await decide(options)
+
+  // Then request approval
+  const { approve } = await import('./approve.js')
+  const approval = await approve(
+    `Approve decision: ${decision.choice}`,
+    { id: approver },
+    {
+      via: 'slack',
+      context: {
+        decision,
+        options: options.options,
+        context: options.context,
+      },
+    }
+  )
+
+  return {
+    ...decision,
+    approved: approval.approved,
+    approvedBy: approval.approvedBy?.id ?? approval.approvedBy?.name,
+  }
+}

package/src/do.ts

@@ -0,0 +1,275 @@
+/**
+ * Task execution functionality for digital workers
+ */
+
+import { define } from 'ai-functions'
+import type { TaskResult, DoOptions } from './types.js'
+
+/**
+ * Execute a task
+ *
+ * Routes tasks to appropriate workers (AI or human) based on complexity
+ * and requirements. Handles retries, timeouts, and background execution.
+ *
+ * @param task - Description of the task to execute
+ * @param options - Execution options (retries, timeout, background, etc.)
+ * @returns Promise resolving to task result
+ *
+ * @example
+ * ```ts
+ * // Execute a simple task
+ * const result = await do('Generate monthly sales report', {
+ *   timeout: 60000, // 1 minute
+ *   context: {
+ *     month: 'January',
+ *     year: 2024,
+ *   },
+ * })
+ *
+ * if (result.success) {
+ *   console.log('Report:', result.result)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Execute with retries
+ * const result = await do('Sync data to backup server', {
+ *   maxRetries: 3,
+ *   timeout: 30000,
+ *   context: {
+ *     source: 'primary-db',
+ *     destination: 'backup-db',
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Execute in background
+ * const result = await do('Process large dataset', {
+ *   background: true,
+ *   context: {
+ *     dataset: 'customer_transactions.csv',
+ *     outputFormat: 'parquet',
+ *   },
+ * })
+ * ```
+ */
+export async function doTask<T = unknown>(
+  task: string,
+  options: DoOptions = {}
+): Promise<TaskResult<T>> {
+  const {
+    maxRetries = 0,
+    timeout,
+    background = false,
+    context,
+  } = options
+
+  const startTime = Date.now()
+  const steps: TaskResult<T>['steps'] = []
+
+  // Use agentic function for complex tasks
+  const taskFn = define.agentic({
+    name: 'executeTask',
+    description: 'Execute a task using available tools and capabilities',
+    args: {
+      task: 'Description of the task to execute',
+      contextInfo: 'Additional context and parameters for the task',
+    },
+    returnType: {
+      result: 'The result of executing the task',
+      steps: ['List of steps taken to complete the task'],
+    },
+    instructions: `Execute the following task:
+
+${task}
+
+${context ? `Context: ${JSON.stringify(context, null, 2)}` : ''}
+
+Work step-by-step to complete the task. Use available tools as needed.
+Document each step you take for transparency.`,
+    maxIterations: 10,
+    tools: [], // Tools would be provided by the execution environment
+  })
+
+  let retries = 0
+  let lastError: Error | undefined
+
+  while (retries <= maxRetries) {
+    try {
+      const response = await Promise.race([
+        taskFn.call({ task, contextInfo: context ? JSON.stringify(context) : '' }),
+        timeout
+          ? new Promise((_, reject) =>
+              setTimeout(() => reject(new Error('Task timeout')), timeout)
+            )
+          : new Promise(() => {}), // Never resolves if no timeout
+      ]) as unknown
+
+      const typedResponse = response as { result: T; steps?: Array<{ action: string; result: unknown }> }
+
+      // Track steps if provided
+      if (typedResponse.steps) {
+        steps.push(
+          ...typedResponse.steps.map((step) => ({
+            ...step,
+            timestamp: new Date(),
+          }))
+        )
+      }
+
+      const duration = Date.now() - startTime
+
+      return {
+        result: typedResponse.result,
+        success: true,
+        duration,
+        steps,
+      }
+    } catch (error) {
+      lastError = error as Error
+      retries++
+
+      if (retries <= maxRetries) {
+        steps.push({
+          action: `Retry attempt ${retries}`,
+          result: { error: lastError.message },
+          timestamp: new Date(),
+        })
+
+        // Exponential backoff
+        await new Promise((resolve) =>
+          setTimeout(resolve, Math.pow(2, retries) * 1000)
+        )
+      }
+    }
+  }
+
+  const duration = Date.now() - startTime
+
+  return {
+    result: undefined as T,
+    success: false,
+    error: lastError?.message || 'Task failed',
+    duration,
+    steps,
+  }
+}
+
+// Export as 'do' with proper typing
+export { doTask as do }
+
+/**
+ * Execute multiple tasks in parallel
+ *
+ * @param tasks - Array of tasks to execute
+ * @param options - Execution options
+ * @returns Promise resolving to array of task results
+ *
+ * @example
+ * ```ts
+ * const results = await do.parallel([
+ *   'Generate sales report',
+ *   'Generate marketing report',
+ *   'Generate finance report',
+ * ], {
+ *   timeout: 60000,
+ * })
+ *
+ * const successful = results.filter(r => r.success)
+ * console.log(`Completed ${successful.length} of ${results.length} tasks`)
+ * ```
+ */
+doTask.parallel = async <T = unknown>(
+  tasks: string[],
+  options: DoOptions = {}
+): Promise<Array<TaskResult<T>>> => {
+  return Promise.all(tasks.map((task) => doTask<T>(task, options)))
+}
+
+/**
+ * Execute tasks in sequence
+ *
+ * @param tasks - Array of tasks to execute sequentially
+ * @param options - Execution options
+ * @returns Promise resolving to array of task results
+ *
+ * @example
+ * ```ts
+ * const results = await do.sequence([
+ *   'Backup database',
+ *   'Run migrations',
+ *   'Restart application',
+ * ], {
+ *   maxRetries: 1,
+ * })
+ * ```
+ */
+doTask.sequence = async <T = unknown>(
+  tasks: string[],
+  options: DoOptions = {}
+): Promise<Array<TaskResult<T>>> => {
+  const results: Array<TaskResult<T>> = []
+
+  for (const task of tasks) {
+    const result = await doTask<T>(task, options)
+    results.push(result)
+
+    // Stop if a task fails (unless we're continuing on error)
+    if (!result.success && !options.context?.continueOnError) {
+      break
+    }
+  }
+
+  return results
+}
+
+/**
+ * Execute a task with specific dependencies
+ *
+ * @param task - The task to execute
+ * @param dependencies - Tasks that must complete first
+ * @param options - Execution options
+ * @returns Promise resolving to task result
+ *
+ * @example
+ * ```ts
+ * const result = await do.withDependencies(
+ *   'Deploy application',
+ *   ['Run tests', 'Build artifacts', 'Get approval'],
+ *   { maxRetries: 1 }
+ * )
+ * ```
+ */
+doTask.withDependencies = async <T = unknown>(
+  task: string,
+  dependencies: string[],
+  options: DoOptions = {}
+): Promise<TaskResult<T>> => {
+  // Execute dependencies in sequence
+  const depResults = await doTask.sequence(dependencies, options)
+
+  // Check if all dependencies succeeded
+  const allSuccessful = depResults.every((r) => r.success)
+
+  if (!allSuccessful) {
+    const failed = depResults.filter((r) => !r.success)
+    return {
+      result: undefined as T,
+      success: false,
+      error: `Dependencies failed: ${failed.map((r) => r.error).join(', ')}`,
+      duration: 0,
+    }
+  }
+
+  // Execute main task with dependency results as context
+  return doTask<T>(task, {
+    ...options,
+    context: {
+      ...options.context,
+      dependencies: depResults.map((r) => r.result),
+    },
+  })
+}