digital-workers 2.1.3 → 2.4.0

package/src/transports.ts

@@ -29,23 +29,23 @@ import type {
  * Communication transport - maps contact channels to delivery mechanisms
  */
 export type Transport =
-  | 'email'      // Email transport (SendGrid, Resend, etc.)
-  | 'sms'        // SMS transport (Twilio, etc.)
-  | 'voice'      // Voice call transport (Vapi, Twilio, etc.)
-  | 'slack'      // Slack API
-  | 'teams'      // Microsoft Teams API
-  | 'discord'    // Discord API
-  | 'whatsapp'   // WhatsApp Business API
-  | 'telegram'   // Telegram Bot API
-  | 'web'        // Web push/in-app
-  | 'webhook'    // Generic webhook
+  | 'email' // Email transport (SendGrid, Resend, etc.)
+  | 'sms' // SMS transport (Twilio, etc.)
+  | 'voice' // Voice call transport (Vapi, Twilio, etc.)
+  | 'slack' // Slack API
+  | 'teams' // Microsoft Teams API
+  | 'discord' // Discord API
+  | 'whatsapp' // WhatsApp Business API
+  | 'telegram' // Telegram Bot API
+  | 'web' // Web push/in-app
+  | 'webhook' // Generic webhook
 
 /**
  * Transport configuration
  */
 export interface TransportConfig {
   transport: Transport
-  provider?: string        // Specific provider (e.g., 'sendgrid', 'resend')
+  provider?: string // Specific provider (e.g., 'sendgrid', 'resend')
   apiKey?: string
   apiUrl?: string
   options?: Record<string, unknown>
@@ -73,7 +73,7 @@ export interface MessagePayload {
 
   // Interactive (for questions/approvals)
   actions?: MessageAction[]
-  schema?: unknown  // SimpleSchema from ai-functions
+  schema?: unknown // SimpleSchema from ai-functions
   timeout?: number
 }
 
@@ -151,16 +151,16 @@ export function getTeamTransports(team: Team): Transport[] {
 
   // Add team-level contacts
   const contacts = team.contacts
-  if (contacts.email) transports.add('email')
-  if (contacts.slack) transports.add('slack')
-  if (contacts.teams) transports.add('teams')
-  if (contacts.discord) transports.add('discord')
-  if (contacts.phone) transports.add('voice')
-  if (contacts.sms) transports.add('sms')
-  if (contacts.whatsapp) transports.add('whatsapp')
-  if (contacts.telegram) transports.add('telegram')
-  if (contacts.web) transports.add('web')
-  if (contacts.webhook) transports.add('webhook')
+  if (contacts?.['email']) transports.add('email')
+  if (contacts?.['slack']) transports.add('slack')
+  if (contacts?.['teams']) transports.add('teams')
+  if (contacts?.['discord']) transports.add('discord')
+  if (contacts?.['phone']) transports.add('voice')
+  if (contacts?.['sms']) transports.add('sms')
+  if (contacts?.['whatsapp']) transports.add('whatsapp')
+  if (contacts?.['telegram']) transports.add('telegram')
+  if (contacts?.['web']) transports.add('web')
+  if (contacts?.['webhook']) transports.add('webhook')
 
   return Array.from(transports)
 }
@@ -196,7 +196,11 @@ export function resolveAddress(contacts: Contacts, channel: ContactChannel): Add
   switch (channel) {
     case 'email':
       const emailContact = contact as { address: string; name?: string }
-      return { transport, value: emailContact.address, name: emailContact.name }
+      return {
+        transport,
+        value: emailContact.address,
+        ...(emailContact.name !== undefined && { name: emailContact.name }),
+      }
     case 'phone':
     case 'sms':
     case 'whatsapp':
@@ -246,8 +250,17 @@ export function resolveAddress(contacts: Contacts, channel: ContactChannel): Add
 export function resolveWorkerAddresses(worker: Worker): Address[] {
   const addresses: Address[] = []
   const channels: ContactChannel[] = [
-    'email', 'slack', 'teams', 'discord', 'phone', 'sms',
-    'whatsapp', 'telegram', 'web', 'api', 'webhook',
+    'email',
+    'slack',
+    'teams',
+    'discord',
+    'phone',
+    'sms',
+    'whatsapp',
+    'telegram',
+    'web',
+    'api',
+    'webhook',
   ]
 
   for (const channel of channels) {
@@ -365,9 +378,7 @@ export async function sendToMultipleTransports(
   configs?: Record<Transport, TransportConfig>
 ): Promise<DeliveryResult[]> {
   const results = await Promise.all(
-    transports.map(transport =>
-      sendViaTransport(transport, payload, configs?.[transport])
-    )
+    transports.map((transport) => sendViaTransport(transport, payload, configs?.[transport]))
   )
   return results
 }
@@ -385,7 +396,7 @@ export function buildNotifyPayload(action: NotifyActionData): MessagePayload {
     body: action.message,
     type: 'notification',
     priority: action.priority || 'normal',
-    metadata: action.metadata,
+    ...(action.metadata !== undefined && { metadata: action.metadata }),
   }
 }
 
@@ -397,9 +408,9 @@ export function buildAskPayload(action: AskActionData): MessagePayload {
     to: resolveActionTarget(action.object),
     body: action.question,
     type: 'question',
-    schema: action.schema,
-    timeout: action.timeout,
-    metadata: action.metadata,
+    ...(action.schema !== undefined && { schema: action.schema }),
+    ...(action.timeout !== undefined && { timeout: action.timeout }),
+    ...(action.metadata !== undefined && { metadata: action.metadata }),
   }
 }
 
@@ -411,7 +422,7 @@ export function buildApprovePayload(action: ApproveActionData): MessagePayload {
     to: resolveActionTarget(action.object),
     body: action.request,
     type: 'approval',
-    timeout: action.timeout,
+    ...(action.timeout !== undefined && { timeout: action.timeout }),
     actions: [
       { id: 'approve', label: 'Approve', style: 'primary', value: true },
       { id: 'reject', label: 'Reject', style: 'danger', value: false },
@@ -450,7 +461,7 @@ export const MessageTypeMapping = {
   discord: 'chat',
   whatsapp: 'text',
   telegram: 'text',
-  voice: 'voicemail',  // For voicemail messages
+  voice: 'voicemail', // For voicemail messages
 } as const
 
 /**
@@ -490,15 +501,19 @@ export function toDigitalToolsMessage(
 /**
  * Convert digital-tools Message to worker notification format
  */
-export function fromDigitalToolsMessage(
-  message: Record<string, unknown>
-): Partial<MessagePayload> {
+export function fromDigitalToolsMessage(message: Record<string, unknown>): Partial<MessagePayload> {
+  const to = message['to'] as string | string[]
+  const from = message['from'] as string | undefined
+  const subject = message['subject'] as string | undefined
+  const body = message['body'] as string
+  const html = message['html'] as string | undefined
+  const metadata = message['metadata'] as Record<string, unknown> | undefined
   return {
-    to: message.to as string | string[],
-    from: message.from as string | undefined,
-    subject: message.subject as string | undefined,
-    body: message.body as string,
-    html: message.html as string | undefined,
-    metadata: message.metadata as Record<string, unknown> | undefined,
+    to,
+    body,
+    ...(from !== undefined && { from }),
+    ...(subject !== undefined && { subject }),
+    ...(html !== undefined && { html }),
+    ...(metadata !== undefined && { metadata }),
   }
 }

package/src/types.ts

@@ -17,8 +17,41 @@
  */
 
 import type { SimpleSchema } from 'ai-functions'
+import type { Thing, ThingRef } from 'digital-objects'
+import type { ThingRef as SchemaThingRef } from 'schema.org.ai'
 import type { CapabilityTier, CapabilityProfile } from './capability-tiers.js'
 
+// Import consolidated types from org.ai
+import type { Role, Team, Goal, Goals, KPI, OKR, TeamMember, KeyResult } from 'org.ai'
+
+// Re-export org.ai types for convenience
+export type { Role, Team, Goal, Goals, KPI, OKR, TeamMember, KeyResult }
+
+// Re-export digital-objects core types used by Worker/Role surfaces
+export type { Thing, ThingRef }
+
+// ============================================================================
+// Identity (SVO co-design — aip-ttfk)
+// ============================================================================
+
+/**
+ * IdentityRef — reference to an `id.org.ai` Identity record.
+ *
+ * Widened from the `string`-only placeholder introduced in aip-ttfk to the
+ * `schema.org.ai` `ThingRef` shape now that the upstream package has shipped
+ * (`schema.org.ai@^0.1.0`). Two shapes are accepted:
+ *   - bare string `$id` (back-compat with the original `IdentityRef = string`)
+ *   - `{ $id, $type, name? }` typed reference, so callers can route by class
+ *     without first resolving the Identity record.
+ *
+ * Per the SVO co-design plan (`docs/plans/2026-05-05-svo-co-design.md`,
+ * step 4), a `Worker` carries an `IdentityRef` so AuthBroker and
+ * PaymentBroker can gate Tool invocations on the worker's scopes and
+ * funding instruments. The typed form lets `Worker.resolve()` skip a
+ * fetch when `$type` is already known.
+ */
+export type IdentityRef = SchemaThingRef
+
 // ============================================================================
 // Worker Types
 // ============================================================================
@@ -32,10 +65,10 @@ export type WorkerType = 'agent' | 'human'
  * Worker status
  */
 export type WorkerStatus =
-  | 'available'    // Ready to accept work
-  | 'busy'         // Currently working
-  | 'away'         // Not available (break, offline)
-  | 'offline'      // Disconnected
+  | 'available' // Ready to accept work
+  | 'busy' // Currently working
+  | 'away' // Not available (break, offline)
+  | 'offline' // Disconnected
 
 // ============================================================================
 // Contact Channel Types
@@ -45,17 +78,17 @@ export type WorkerStatus =
  * Contact channel names - how workers can be reached
  */
 export type ContactChannel =
-  | 'email'      // Email communication
-  | 'slack'      // Slack workspace
-  | 'teams'      // Microsoft Teams
-  | 'discord'    // Discord server
-  | 'phone'      // Voice calls
-  | 'sms'        // SMS text messages
-  | 'whatsapp'   // WhatsApp messaging
-  | 'telegram'   // Telegram messaging
-  | 'web'        // Web UI/dashboard
-  | 'api'        // Programmatic API
-  | 'webhook'    // Webhook callbacks
+  | 'email' // Email communication
+  | 'slack' // Slack workspace
+  | 'teams' // Microsoft Teams
+  | 'discord' // Discord server
+  | 'phone' // Voice calls
+  | 'sms' // SMS text messages
+  | 'whatsapp' // WhatsApp messaging
+  | 'telegram' // Telegram messaging
+  | 'web' // Web UI/dashboard
+  | 'api' // Programmatic API
+  | 'webhook' // Webhook callbacks
 
 /**
  * Email contact - simple string or config object
@@ -239,6 +272,13 @@ export interface Worker {
   capabilityTier?: CapabilityTier
   /** Full capability profile for detailed configuration */
   capabilityProfile?: CapabilityProfile
+  /**
+   * Reference to this Worker's `id.org.ai` Identity record (DID + scopes +
+   * payment instruments). Optional for backward compatibility — populated
+   * by deployments that have wired up an `id.org.ai` AuthBroker/
+   * PaymentBroker. SVO co-design step 4 (aip-ttfk).
+   */
+  identity?: IdentityRef
   metadata?: Record<string, unknown>
 }
 
@@ -259,11 +299,15 @@ export interface WorkerRef {
 // ============================================================================
 
 /**
- * Team - group of workers with shared contacts
+ * WorkerTeam - group of workers with shared contacts
+ *
+ * This is the digital-workers team interface that includes
+ * worker-specific contact channels. For the base Team type,
+ * use Team from org.ai.
  *
  * @example
  * ```ts
- * const engineering: Team = {
+ * const engineering: WorkerTeam = {
  *   id: 'team_eng',
  *   name: 'Engineering',
  *   members: [alice, bob, deployBot],
@@ -274,14 +318,22 @@ export interface WorkerRef {
  * }
  * ```
  */
-export interface Team {
+export interface WorkerTeam {
+  /** Team identifier */
   id: string
+  /** Team name */
   name: string
+  /** Team description */
   description?: string
+  /** Team members as WorkerRefs */
   members: WorkerRef[]
+  /** Worker-specific contact channels */
   contacts: Contacts
+  /** Team lead as WorkerRef */
   lead?: WorkerRef
+  /** Team goals */
   goals?: string[]
+  /** Additional metadata */
   metadata?: Record<string, unknown>
 }
 
@@ -623,9 +675,7 @@ export interface WorkerContext {
   /**
    * Make a decision (AI or human)
    */
-  decide<T = string>(
-    options: DecideOptions<T>
-  ): Promise<DecideResult<T>>
+  decide<T = string>(options: DecideOptions<T>): Promise<DecideResult<T>>
 }
 
 // ============================================================================
@@ -679,53 +729,139 @@ export interface DecideOptions<T = string> {
 // ============================================================================
 
 /**
- * Worker role definition
+ * OrgRole — a slot in an org structure (e.g., 'CEO', 'PDM') filled by a
+ * specific Person or Agent.
+ *
+ * SVO co-design step 4 (aip-ttfk). This is the Noun-extending Role from
+ * `docs/plans/2026-05-05-svo-co-design.md`: a `Thing` whose data records
+ * the slot's current `filler` and an optional `fallbackChain` for when
+ * the filler is unavailable. A `Worker` whose `id` references an
+ * `OrgRole` resolves to the current filler at invocation time.
+ *
+ * NAMING NOTE: the design doc calls this type `Role`, but `Role` is
+ * already imported from `org.ai` and re-exported above as a different
+ * concept (a job-description-shaped HR Role with skills, permissions,
+ * responsibilities). Renamed here to `OrgRole` to avoid the collision;
+ * see the aip-ttfk bead comment for the surfaced conflict.
+ *
+ * @example
+ * ```ts
+ * const ceo: OrgRole = {
+ *   id: 'role_ceo',
+ *   noun: 'OrgRole',
+ *   data: {
+ *     $type: 'Role',
+ *     name: 'CEO',
+ *     filler: 'person_priya',
+ *     fallbackChain: ['person_alex'],
+ *   },
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * }
+ * ```
+ */
+export interface OrgRole
+  extends Thing<{
+    $type: 'Role'
+    /** Display name of the slot (e.g., 'CEO', 'PDM') */
+    name: string
+    /** Current filler — a Person or Agent ThingRef */
+    filler: ThingRef
+    /** Fallback fillers tried in order if `filler` is unavailable */
+    fallbackChain?: ThingRef[]
+  }> {}
+
+/**
+ * WorkerRole - extends Role from org.ai with worker-specific requirements
+ *
+ * Inherits all fields from the base Role type (id, name, description, skills,
+ * permissions, tools, outputs, type, department, etc.) and makes responsibilities
+ * required for worker role definitions.
+ *
+ * @example
+ * ```ts
+ * const engineerRole: WorkerRole = {
+ *   id: 'role_engineer',
+ *   name: 'Software Engineer',
+ *   description: 'Builds and maintains software',
+ *   skills: ['typescript', 'react', 'node'],
+ *   responsibilities: ['write code', 'review PRs', 'fix bugs'],
+ * }
+ * ```
  */
-export interface WorkerRole {
-  name: string
-  description: string
+export interface WorkerRole extends Role {
+  /** List of responsibilities (required for worker roles) */
   responsibilities: string[]
-  skills?: string[]
-  permissions?: string[]
-  type?: 'ai' | 'human' | 'hybrid'
 }
 
 /**
- * Worker goals
+ * WorkerGoals - categorized goals with metrics
+ *
+ * Organizes goals by timeframe (short-term, long-term, strategic)
+ * and includes associated KPI metrics for tracking.
+ *
+ * Note: org.ai's Goals is a simpler type (Goal[]). WorkerGoals
+ * provides additional structure for worker/team goal planning
+ * with string-based goals for simplicity.
  */
 export interface WorkerGoals {
+  /** Short-term goals (days to weeks) */
   shortTerm: string[]
+  /** Long-term goals (months to year) */
   longTerm: string[]
+  /** Strategic goals (multi-year vision) */
   strategic?: string[]
-  metrics?: KPI[]
+  /** Associated KPI metrics */
+  metrics?: WorkerKPI[]
 }
 
 /**
- * KPI definition
+ * WorkerKPI - simplified KPI for worker goals
+ *
+ * A simpler KPI interface used in WorkerGoals.metrics.
+ * For the full KPI type with id, category, history, etc.,
+ * use KPI from org.ai.
  */
-export interface KPI {
+export interface WorkerKPI {
+  /** KPI name */
   name: string
+  /** Description of what this measures */
   description: string
+  /** Current value */
   current: number
+  /** Target value */
   target: number
+  /** Unit of measurement */
   unit: string
+  /** Trend direction */
   trend?: 'up' | 'down' | 'stable'
+  /** Measurement period */
   period?: string
 }
 
 /**
- * OKR definition
+ * WorkerOKR - worker-specific OKR definition
+ *
+ * Uses WorkerRef for owner and simplified key results with
+ * required `current` and `target` fields for progress tracking.
+ * For the full org.ai OKR with `id`, `status`, `period`, etc.,
+ * import OKR from 'org.ai' directly.
  */
-export interface OKR {
+export interface WorkerOKR {
+  /** The objective - what you want to achieve */
   objective: string
+  /** Measurable key results */
   keyResults: Array<{
     name: string
     current: number
     target: number
     unit: string
   }>
+  /** Owner as WorkerRef */
   owner?: WorkerRef
+  /** Due date */
   dueDate?: Date
+  /** Overall progress percentage */
   progress?: number
 }
 
@@ -784,13 +920,7 @@ export interface DoOptions {
 /**
  * Content type for generation
  */
-export type GenerationType =
-  | 'text'
-  | 'code'
-  | 'structured'
-  | 'image'
-  | 'video'
-  | 'audio'
+export type GenerationType = 'text' | 'code' | 'structured' | 'image' | 'video' | 'audio'
 
 /**
  * Options for content generation
@@ -842,10 +972,8 @@ export interface TypeCheckResult<T = unknown> {
 }
 
 // ============================================================================
-// Team Alias
+// Team Alias - Backwards Compatibility
 // ============================================================================
 
-/**
- * @deprecated Use Team instead
- */
-export type WorkerTeam = Team
+// WorkerTeam is now the primary type that extends Team from org.ai
+// The base Team type is re-exported from org.ai

package/src/utils/id.ts

@@ -0,0 +1,21 @@
+/**
+ * ID generation utilities for request tracking across transports
+ */
+
+/**
+ * Generate a unique request ID with the specified prefix.
+ *
+ * Format: `{prefix}_{timestamp}_{random}`
+ * - prefix: Customizable identifier (default: 'req')
+ * - timestamp: Unix timestamp in milliseconds
+ * - random: 9-character base36 random string
+ *
+ * @example
+ * ```ts
+ * generateRequestId()      // 'req_1706454932123_k7x3m9n2p'
+ * generateRequestId('apr') // 'apr_1706454932123_k7x3m9n2p'
+ * ```
+ */
+export function generateRequestId(prefix: string = 'req'): string {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`
+}