digital-workers 0.1.1 → 2.0.2

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> digital-workers@2.0.1 build /Users/nathanclevenger/projects/primitives.org.ai/packages/digital-workers
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# digital-workers
+
+## 2.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-functions@2.0.2
+  - ai-workflows@2.0.2
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-functions@2.0.1
+  - ai-workflows@2.0.1

package/README.md

@@ -1,153 +1,337 @@
 # digital-workers
 
-[![npm version](https://img.shields.io/npm/v/digital-workers.svg)](https://www.npmjs.com/package/digital-workers)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+Abstract interface for organizing digital work, independent of whether AI or humans perform individual tasks.
 
-Enhanced autonomous digital workers with event loop, KPI tracking, and communication capabilities. This package builds on the `autonomous-agents` infrastructure to create digital workers with advanced features.
+## Overview
 
-## Purpose
+**Digital workers** provides the foundational abstraction for structuring and organizing work in the digital enterprise. It defines a unified interface that both AI agents and humans implement, enabling you to design workflows without coupling them to specific execution strategies.
 
-The `digital-workers` package extends the autonomous agents concept by providing:
+### Why This Abstraction Matters
 
-- Constant event loop for regular evaluation of KPIs against OKRs
-- Context and memory management for long-running tasks
-- Plan creation and execution for achieving objectives
-- Multi-channel communication capabilities (Slack, Teams, Email, Phone)
-- Enhanced autonomy through continuous self-evaluation
+When building AI-powered systems, you face a fundamental question: *who should do this task?* Sometimes it's an AI agent operating autonomously. Sometimes it requires human judgment. Often it's a mix of both.
 
-## How It Builds on autonomous-agents
+`digital-workers` lets you define work in terms of **what** needs to happen, not **who** does it:
 
-The `digital-workers` package uses the function-based `Agent` from `autonomous-agents` as its foundation, adding:
+```typescript
+// This workflow doesn't care if alice is an AI agent or a human
+await worker$.approve('Deploy v2.0 to production', alice, { via: 'slack' })
+```
 
-- **Event Loop**: Continuous evaluation and adjustment based on KPIs
-- **Enhanced Context**: Maintains richer context and memory for improved decision-making
-- **Communication Channels**: Integrated support for multiple communication platforms
-- **KPI Tracking**: Automated tracking and evaluation of key performance indicators
-- **OKR Alignment**: Ensures actions align with organizational objectives and key results
+The same Worker interface works whether `alice` is:
+- A human product manager who gets a Slack notification
+- An AI agent that evaluates deployment criteria autonomously
+- A supervised AI that escalates to humans for high-risk decisions
 
-## Installation
+### Package Relationships
 
-```bash
-# Using npm
-npm install digital-workers
+```
+┌─────────────────────────────────────────────────────────┐
+│                    ai-workflows                         │
+│              (orchestrates work execution)              │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                  digital-workers                        │
+│         (abstract interface for work & workers)         │
+└────────────────────────┬────────────────────────────────┘
+                         │
+           ┌─────────────┴─────────────┐
+           ▼                           ▼
+┌─────────────────────┐   ┌─────────────────────────────┐
+│  autonomous-agents  │   │     human-in-the-loop       │
+│  (AI implementation)│   │   (human implementation)    │
+└─────────────────────┘   └─────────────────────────────┘
+```
+
+- **digital-workers**: Defines the abstract `Worker` interface, action types, and communication patterns
+- **autonomous-agents**: Implements `Worker` for AI agents with autonomous decision-making
+- **human-in-the-loop**: Implements `Worker` for humans with approval workflows and notifications
 
-# Using yarn
-yarn add digital-workers
+## Installation
 
-# Using pnpm
+```bash
 pnpm add digital-workers
 ```
 
-## Usage
+## Core Concepts
+
+### The Worker Abstraction
 
-### Basic Usage
+A **Worker** is the unified interface for any entity that can perform work—whether AI or human. This abstraction enables you to:
+
+1. **Design workflows once** - Define your business logic without hardcoding execution strategy
+2. **Swap implementations** - Start with humans, transition to AI agents as they prove reliable
+3. **Mix freely** - Teams can include both AI agents and humans working together
+4. **Route dynamically** - Assign tasks based on availability, capability, or risk level
+
+### Worker
+
+A **Worker** is the common interface for both AI agents and humans:
 
 ```typescript
-import { Worker } from 'digital-workers'
-
-// Create a digital worker for customer support
-const supportWorker = Worker({
-  name: 'Support Assistant',
-  description: 'Handles customer support inquiries and resolves issues',
-  id: 'support-worker-1',
-  initialContext: {
-    department: 'Customer Support',
-    specialization: 'Technical Issues'
+import type { Worker } from 'digital-workers'
+
+const alice: Worker = {
+  id: 'user_alice',
+  name: 'Alice',
+  type: 'human',
+  status: 'available',
+  contacts: {
+    email: 'alice@company.com',
+    slack: { workspace: 'acme', user: 'U123' },
+    phone: '+1-555-1234',
   },
-  initialPlans: [
-    {
-      name: 'Handle New Tickets',
-      steps: ['Review ticket', 'Categorize issue', 'Respond with solution or escalate']
-    }
-  ],
-  communication: {
-    slack: {
-      token: process.env.SLACK_TOKEN,
-      channels: ['support', 'escalations']
-    },
-    email: {
-      smtp: process.env.SMTP_CONFIG,
-      address: 'support@example.com'
-    }
+}
+
+const codeReviewer: Worker = {
+  id: 'agent_reviewer',
+  name: 'Code Reviewer',
+  type: 'agent',
+  status: 'available',
+  contacts: {
+    api: { endpoint: 'https://api.internal/reviewer', auth: 'bearer' },
+    webhook: { url: 'https://hooks.internal/reviewer' },
+  },
+}
+```
+
+### Contacts
+
+Workers have **contacts** that define how they can be reached:
+
+```typescript
+import type { Contacts } from 'digital-workers'
+
+const contacts: Contacts = {
+  email: 'team@company.com',                    // Simple string
+  slack: { workspace: 'acme', channel: '#eng' }, // Config object
+  phone: { number: '+1-555-0000', voice: 'en-US' },
+  sms: '+1-555-0001',
+  teams: { tenant: 'company', channel: 'Engineering' },
+  discord: { server: 'dev-community', channel: 'support' },
+  telegram: { chat: '@company_support' },
+  web: { url: 'https://dashboard.company.com', pushEnabled: true },
+  api: { endpoint: 'https://api.company.com', auth: 'bearer' },
+  webhook: { url: 'https://hooks.company.com/events' },
+}
+```
+
+### Team
+
+**Teams** group workers with shared contacts:
+
+```typescript
+import { Team } from 'digital-workers'
+
+const engineering = Team({
+  id: 'team_eng',
+  name: 'Engineering',
+  members: [alice, bob, codeReviewer],
+  contacts: {
+    slack: '#engineering',
+    email: 'eng@company.com',
   },
-  eventLoop: {
-    frequency: '*/15 * * * *', // Cron expression for every 15 minutes
-    kpis: ['responseTime', 'resolutionRate', 'customerSatisfaction'],
-    okrs: {
-      responseTime: { target: '< 30 minutes', weight: 0.3 },
-      resolutionRate: { target: '> 85%', weight: 0.4 },
-      customerSatisfaction: { target: '> 4.5/5', weight: 0.3 }
+  lead: alice,
+})
+```
+
+## Worker Actions
+
+Worker actions are durable workflow actions with Actor/Object semantics that integrate with `ai-workflows`:
+
+### Using with Workflows (Recommended)
+
+```typescript
+import { Workflow } from 'ai-workflows'
+import { registerWorkerActions, withWorkers } from 'digital-workers'
+
+const workflow = Workflow($ => {
+  registerWorkerActions($)
+  const worker$ = withWorkers($)
+
+  $.on.Expense.submitted(async (expense) => {
+    // Notify finance team
+    await worker$.notify(finance, `New expense: ${expense.amount}`)
+
+    // Request approval from manager
+    const approval = await worker$.approve(
+      `Expense: $${expense.amount} for ${expense.description}`,
+      manager,
+      { via: 'slack' }
+    )
+
+    if (approval.approved) {
+      await worker$.notify(expense.submitter, 'Your expense was approved!')
     }
-  }
+  })
 })
+```
+
+### Direct Workflow Integration
 
-// Execute a task
-const result = await supportWorker.execute({
-  action: 'respondToTicket',
-  ticketId: '12345',
-  message: 'Thank you for your inquiry. Here is the solution...'
+```typescript
+// Using $.do for durable actions
+await $.do('Worker.notify', {
+  actor: 'system',
+  object: alice,
+  action: 'notify',
+  message: 'Deployment complete',
+  via: 'slack',
 })
 
-// Update worker context
-await supportWorker.updateContext({
-  currentLoad: 'high',
-  priorityIssues: ['server-outage', 'payment-processing']
+// Using $.send for fire-and-forget
+await $.send('Worker.notified', { ... })
+```
+
+### Action Types
+
+#### notify - Send notifications
+
+```typescript
+await worker$.notify(target, 'Message content', {
+  via: 'slack',           // Channel to use
+  priority: 'urgent',     // 'low' | 'normal' | 'high' | 'urgent'
 })
+```
+
+#### ask - Request information
+
+```typescript
+const result = await worker$.ask<Priority>(
+  target,
+  'What priority should this be?',
+  {
+    via: 'slack',
+    schema: { priority: 'low | normal | high' },
+  }
+)
+console.log(result.answer) // { priority: 'high' }
+```
+
+#### approve - Request approval
 
-// Send a message via configured channels
-await supportWorker.sendMessage('slack', {
-  channel: 'support',
-  message: 'New high-priority issue detected: server outage'
+```typescript
+const result = await worker$.approve(
+  'Deploy v2.0 to production',
+  manager,
+  {
+    via: 'slack',
+    context: { version: '2.0', environment: 'production' },
+    timeout: 3600000, // 1 hour
+  }
+)
+
+if (result.approved) {
+  console.log(`Approved by ${result.approvedBy?.name}`)
+}
+```
+
+#### decide - AI-powered decisions
+
+```typescript
+const result = await worker$.decide({
+  options: ['React', 'Vue', 'Svelte'],
+  context: 'Choosing a frontend framework for our new project',
+  criteria: ['DX', 'Performance', 'Ecosystem'],
 })
+
+console.log(result.choice)     // 'React'
+console.log(result.reasoning)  // 'React offers the best ecosystem...'
+console.log(result.confidence) // 0.85
+```
+
+## Standalone Functions
+
+For use outside workflows:
+
+```typescript
+import { notify, ask, approve, decide } from 'digital-workers'
+
+// Simple notification
+await notify(alice, 'Task completed', { via: 'slack' })
+
+// Ask with variants
+await ask(alice, 'What is the status?')
+await ask.ai('What is our refund policy?', { policies: [...] })
+await ask.yesNo(manager, 'Should we proceed?')
+
+// Approval variants
+await approve('Deploy to production', manager)
+await approve.all('Major change', [cto, vpe, securityLead])
+await approve.any('Urgent fix', oncallTeam)
+
+// Decision making
+await decide({ options: ['A', 'B', 'C'], criteria: ['cost', 'time'] })
+await decide.yesNo('Should we proceed?', context)
+await decide.prioritize(['Task 1', 'Task 2', 'Task 3'])
 ```
 
-## API Reference
+## Additional Utilities
 
-### Worker(config)
+### Role Definition
 
-Creates a new digital worker with the provided configuration.
+```typescript
+import { Role } from 'digital-workers'
+
+const engineer = Role({
+  name: 'Software Engineer',
+  description: 'Builds and maintains software',
+  responsibilities: ['Write code', 'Review PRs', 'Fix bugs'],
+  skills: ['TypeScript', 'React', 'Node.js'],
+})
+```
 
-**Parameters:**
+### Goals & KPIs
 
-- `config` (WorkerConfig): The configuration for the worker
+```typescript
+import { Goals, kpis, okrs } from 'digital-workers'
 
-**Returns:**
+const teamGoals = Goals({
+  shortTerm: ['Ship v2.0', 'Reduce tech debt'],
+  longTerm: ['100% test coverage'],
+  metrics: [
+    { name: 'Velocity', current: 42, target: 50, unit: 'points' },
+  ],
+})
+```
 
-- (WorkerInstance): A digital worker instance
+### Content Generation
 
-### WorkerConfig
+```typescript
+import { generate } from 'digital-workers'
 
-The configuration object for creating a worker.
+const result = await generate('Write a product description', {
+  type: 'text',
+  instructions: 'Keep it under 100 words',
+})
+```
 
-| Property       | Type                    | Description                                       |
-| -------------- | ----------------------- | ------------------------------------------------- |
-| name           | string                  | The name of the worker                            |
-| description    | string                  | Description of the worker's purpose               |
-| id             | string (optional)       | Unique identifier for the worker                  |
-| initialContext | object (optional)       | Initial context data for the worker               |
-| initialPlans   | Plan[] (optional)       | Initial plans for the worker to execute           |
-| communication  | CommunicationConfig     | Configuration for communication channels          |
-| eventLoop      | EventLoopConfig         | Configuration for the event loop and KPI tracking |
+### Type Validation
 
-### WorkerInstance
+```typescript
+import { is } from 'digital-workers'
 
-The worker instance returned by the Worker function.
+const result = await is('hello@example.com', 'email')
+console.log(result.valid) // true
+```
 
-| Property/Method | Type                                                | Description                                           |
-| --------------- | --------------------------------------------------- | ----------------------------------------------------- |
-| id              | string                                              | Unique identifier for the worker                      |
-| agent           | AutonomousAgent                                     | The underlying autonomous agent                       |
-| context         | object                                              | Current context data for the worker                   |
-| plans           | Plan[]                                              | Current plans for the worker                          |
-| execute         | (input: any) => Promise<any>                        | Executes an action using the underlying agent         |
-| updateContext   | (newContext: any) => Promise<void>                  | Updates the worker's context                          |
-| sendMessage     | (channel: string, message: any) => Promise<void>    | Sends a message via the specified communication channel |
+## Type Reference
 
-## Dependencies
+Key types exported:
 
-- autonomous-agents: For the underlying agent functionality
-- Node.js 18+: For native features like fetch API
+- `Worker` - Worker interface
+- `Team` - Team interface
+- `WorkerRef` - Lightweight worker reference
+- `Contacts` - Contact configuration
+- `ContactChannel` - Channel names
+- `WorkerAction` - Action types
+- `NotifyResult`, `AskResult`, `ApprovalResult`, `DecideResult`, `DoResult`
+- `WorkerContext` - Context extension for workflows
 
-## License
+## Related Packages
 
-MIT
+- `autonomous-agents` - **Implements** `Worker` for AI agents with autonomous decision-making, goals, and metrics
+- `human-in-the-loop` - **Implements** `Worker` for humans with approval workflows, notifications, and escalation
+- `ai-workflows` - **Uses** `digital-workers` to orchestrate work execution with durable, event-driven workflows
+- `services-as-software` - External service integration (crosses company boundaries, unlike workers)

package/dist/actions.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Worker Actions - Workflow Integration
+ *
+ * Worker actions (notify, ask, approve, decide, do) are durable workflow actions
+ * that integrate with ai-workflows. They can be invoked via:
+ *
+ * 1. `$.do('Worker.notify', data)` - Durable action
+ * 2. `$.send('Worker.notify', data)` - Fire and forget
+ * 3. `$.notify(target, message)` - Convenience method (when using withWorkers)
+ *
+ * @packageDocumentation
+ */
+import type { WorkflowContext } from 'ai-workflows';
+import type { ActionTarget, NotifyActionData, AskActionData, ApproveActionData, DecideActionData, DoActionData, NotifyResult, AskResult, ApprovalResult, DecideResult, DoResult, NotifyOptions, AskOptions, ApproveOptions, DecideOptions, WorkerContext } from './types.js';
+/**
+ * Handle Worker.notify action
+ */
+export declare function handleNotify(data: NotifyActionData, $: WorkflowContext): Promise<NotifyResult>;
+/**
+ * Handle Worker.ask action
+ */
+export declare function handleAsk<T = string>(data: AskActionData, $: WorkflowContext): Promise<AskResult<T>>;
+/**
+ * Handle Worker.approve action
+ */
+export declare function handleApprove(data: ApproveActionData, $: WorkflowContext): Promise<ApprovalResult>;
+/**
+ * Handle Worker.decide action
+ */
+export declare function handleDecide<T = string>(data: DecideActionData, $: WorkflowContext): Promise<DecideResult<T>>;
+/**
+ * Handle Worker.do action
+ */
+export declare function handleDo<T = unknown>(data: DoActionData, $: WorkflowContext): Promise<DoResult<T>>;
+/**
+ * Register Worker action handlers with a workflow
+ *
+ * @example
+ * ```ts
+ * import { Workflow } from 'ai-workflows'
+ * import { registerWorkerActions } from 'digital-workers'
+ *
+ * const workflow = Workflow($ => {
+ *   registerWorkerActions($)
+ *
+ *   $.on.Expense.submitted(async (expense, $) => {
+ *     const approval = await $.do('Worker.approve', {
+ *       actor: 'system',
+ *       object: manager,
+ *       request: `Expense: $${expense.amount}`,
+ *       via: 'slack',
+ *     })
+ *   })
+ * })
+ * ```
+ */
+export declare function registerWorkerActions($: WorkflowContext): void;
+/**
+ * Extend WorkflowContext with convenience methods for worker actions
+ *
+ * @example
+ * ```ts
+ * const workflow = Workflow($ => {
+ *   const worker$ = withWorkers($)
+ *
+ *   $.on.Expense.submitted(async (expense) => {
+ *     await worker$.notify(finance, `New expense: ${expense.amount}`)
+ *
+ *     const approval = await worker$.approve(
+ *       `Expense: $${expense.amount}`,
+ *       manager,
+ *       { via: 'slack' }
+ *     )
+ *   })
+ * })
+ * ```
+ */
+export declare function withWorkers($: WorkflowContext): WorkflowContext & WorkerContext;
+/**
+ * Send a notification (standalone, non-durable)
+ */
+export declare function notify(target: ActionTarget, message: string, options?: NotifyOptions): Promise<NotifyResult>;
+/**
+ * Ask a question (standalone, non-durable)
+ */
+export declare function ask<T = string>(target: ActionTarget, question: string, options?: AskOptions): Promise<AskResult<T>>;
+/**
+ * Request approval (standalone, non-durable)
+ */
+export declare function approve(request: string, target: ActionTarget, options?: ApproveOptions): Promise<ApprovalResult>;
+/**
+ * Make a decision (standalone, non-durable)
+ */
+export declare function decide<T = string>(options: DecideOptions<T>): Promise<DecideResult<T>>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAIV,YAAY,EAGZ,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAA;AAMnB;;GAEG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,CAAC,EAAE,eAAe,GACjB,OAAO,CAAC,YAAY,CAAC,CAkDvB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,MAAM,EACxC,IAAI,EAAE,aAAa,EACnB,CAAC,EAAE,eAAe,GACjB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CA4BvB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,iBAAiB,EACvB,CAAC,EAAE,eAAe,GACjB,OAAO,CAAC,cAAc,CAAC,CAiCzB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,EAC3C,IAAI,EAAE,gBAAgB,EACtB,CAAC,EAAE,eAAe,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAU1B;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,YAAY,EAClB,CAAC,EAAE,eAAe,GACjB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAyDtB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAY9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,eAAe,GAAG,eAAe,GAAG,aAAa,CAgE/E;AAMD;;GAEG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA2BvB;AAED;;GAEG;AACH,wBAAsB,GAAG,CAAC,CAAC,GAAG,MAAM,EAClC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAgBvB;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAiBzB;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,GAAG,MAAM,EACrC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAE1B"}