digital-workers 2.0.1 → 2.1.1

package/src/team.js

@@ -0,0 +1,130 @@
+/**
+ * Team definition for digital workers
+ */
+/**
+ * Define a team of workers
+ *
+ * Teams organize workers (AI agents and humans) into cohesive units
+ * with shared goals and responsibilities.
+ *
+ * @param definition - Team definition
+ * @returns The defined team
+ *
+ * @example
+ * ```ts
+ * const engineeringTeam = Team({
+ *   name: 'Engineering',
+ *   description: 'Product engineering team',
+ *   members: [
+ *     { id: 'alice', name: 'Alice', role: 'Senior Engineer', type: 'human' },
+ *     { id: 'bob', name: 'Bob', role: 'Engineer', type: 'human' },
+ *     { id: 'ai-reviewer', name: 'Code Reviewer', role: 'Code Reviewer', type: 'ai' },
+ *     { id: 'ai-tester', name: 'Test Generator', role: 'Test Engineer', type: 'ai' },
+ *   ],
+ *   goals: [
+ *     'Ship features on schedule',
+ *     'Maintain code quality',
+ *     'Reduce technical debt',
+ *   ],
+ *   lead: 'alice',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const supportTeam = Team({
+ *   name: 'Customer Support',
+ *   description: '24/7 customer support team',
+ *   members: [
+ *     { id: 'support-ai-1', name: 'Support Bot Alpha', role: 'Support Agent', type: 'ai' },
+ *     { id: 'support-ai-2', name: 'Support Bot Beta', role: 'Support Agent', type: 'ai' },
+ *     { id: 'escalation-human', name: 'Jane', role: 'Senior Support', type: 'human' },
+ *   ],
+ *   goals: [
+ *     'Maintain 95% satisfaction rate',
+ *     'Response time under 5 minutes',
+ *     'First contact resolution > 80%',
+ *   ],
+ *   lead: 'escalation-human',
+ * })
+ * ```
+ */
+export function Team(definition) {
+    return definition;
+}
+/**
+ * Add a member to a team
+ *
+ * @param team - The team to add to
+ * @param member - The member to add
+ * @returns Updated team
+ *
+ * @example
+ * ```ts
+ * const updatedTeam = Team.addMember(engineeringTeam, {
+ *   id: 'charlie',
+ *   name: 'Charlie',
+ *   role: 'Junior Engineer',
+ *   type: 'human',
+ * })
+ * ```
+ */
+Team.addMember = (team, member) => ({
+    ...team,
+    members: [...team.members, member],
+});
+/**
+ * Remove a member from a team
+ *
+ * @param team - The team to remove from
+ * @param memberId - ID of the member to remove
+ * @returns Updated team
+ *
+ * @example
+ * ```ts
+ * const updatedTeam = Team.removeMember(engineeringTeam, 'bob')
+ * ```
+ */
+Team.removeMember = (team, memberId) => ({
+    ...team,
+    members: team.members.filter((m) => m.id !== memberId),
+});
+/**
+ * Get all AI members of a team
+ *
+ * @param team - The team
+ * @returns Array of AI members
+ *
+ * @example
+ * ```ts
+ * const aiMembers = Team.aiMembers(supportTeam)
+ * console.log(aiMembers) // [Support Bot Alpha, Support Bot Beta]
+ * ```
+ */
+Team.aiMembers = (team) => team.members.filter((m) => m.type === 'agent');
+/**
+ * Get all human members of a team
+ *
+ * @param team - The team
+ * @returns Array of human members
+ *
+ * @example
+ * ```ts
+ * const humans = Team.humanMembers(engineeringTeam)
+ * console.log(humans) // [Alice, Bob]
+ * ```
+ */
+Team.humanMembers = (team) => team.members.filter((m) => m.type === 'human');
+/**
+ * Get members by role
+ *
+ * @param team - The team
+ * @param role - Role to filter by
+ * @returns Array of members with that role
+ *
+ * @example
+ * ```ts
+ * const engineers = Team.byRole(engineeringTeam, 'Engineer')
+ * ```
+ */
+Team.byRole = (team, role) => team.members.filter((m) => m.role === role);

package/src/transports.js

@@ -0,0 +1,357 @@
+/**
+ * Communication Transports Bridge
+ *
+ * Connects digital-workers contact channels to digital-tools
+ * communication providers (Message, Call).
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Channel to Transport Mapping
+// =============================================================================
+/**
+ * Map contact channel to transport
+ */
+export function channelToTransport(channel) {
+    const mapping = {
+        email: 'email',
+        slack: 'slack',
+        teams: 'teams',
+        discord: 'discord',
+        phone: 'voice',
+        sms: 'sms',
+        whatsapp: 'whatsapp',
+        telegram: 'telegram',
+        web: 'web',
+        api: 'webhook',
+        webhook: 'webhook',
+    };
+    return mapping[channel] || 'webhook';
+}
+/**
+ * Get available transports for a worker
+ */
+export function getWorkerTransports(worker) {
+    const transports = [];
+    const contacts = worker.contacts;
+    if (contacts.email)
+        transports.push('email');
+    if (contacts.slack)
+        transports.push('slack');
+    if (contacts.teams)
+        transports.push('teams');
+    if (contacts.discord)
+        transports.push('discord');
+    if (contacts.phone)
+        transports.push('voice');
+    if (contacts.sms)
+        transports.push('sms');
+    if (contacts.whatsapp)
+        transports.push('whatsapp');
+    if (contacts.telegram)
+        transports.push('telegram');
+    if (contacts.web)
+        transports.push('web');
+    if (contacts.webhook)
+        transports.push('webhook');
+    return transports;
+}
+/**
+ * Get team transports (union of all member transports + team contacts)
+ */
+export function getTeamTransports(team) {
+    const transports = new Set();
+    // 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');
+    return Array.from(transports);
+}
+/**
+ * Resolve contact to address
+ */
+export function resolveAddress(contacts, channel) {
+    const contact = contacts[channel];
+    if (!contact)
+        return null;
+    const transport = channelToTransport(channel);
+    if (typeof contact === 'string') {
+        return { transport, value: contact };
+    }
+    // Handle structured contact types
+    switch (channel) {
+        case 'email':
+            const emailContact = contact;
+            return { transport, value: emailContact.address, name: emailContact.name };
+        case 'phone':
+        case 'sms':
+        case 'whatsapp':
+            const phoneContact = contact;
+            return { transport, value: phoneContact.number };
+        case 'slack':
+            const slackContact = contact;
+            return {
+                transport,
+                value: slackContact.user || slackContact.channel || '',
+                metadata: { workspace: slackContact.workspace },
+            };
+        case 'teams':
+            const teamsContact = contact;
+            return {
+                transport,
+                value: teamsContact.user || teamsContact.channel || '',
+                metadata: { team: teamsContact.team },
+            };
+        case 'discord':
+            const discordContact = contact;
+            return {
+                transport,
+                value: discordContact.user || discordContact.channel || '',
+                metadata: { server: discordContact.server },
+            };
+        case 'telegram':
+            const telegramContact = contact;
+            return { transport, value: telegramContact.user || telegramContact.chat || '' };
+        case 'web':
+            const webContact = contact;
+            return { transport, value: webContact.userId || '', metadata: { url: webContact.url } };
+        case 'webhook':
+            const webhookContact = contact;
+            return { transport, value: webhookContact.url, metadata: { secret: webhookContact.secret } };
+        case 'api':
+            const apiContact = contact;
+            return { transport, value: apiContact.endpoint, metadata: { auth: apiContact.auth } };
+        default:
+            return null;
+    }
+}
+/**
+ * Resolve all addresses for a worker
+ */
+export function resolveWorkerAddresses(worker) {
+    const addresses = [];
+    const channels = [
+        'email', 'slack', 'teams', 'discord', 'phone', 'sms',
+        'whatsapp', 'telegram', 'web', 'api', 'webhook',
+    ];
+    for (const channel of channels) {
+        const address = resolveAddress(worker.contacts, channel);
+        if (address)
+            addresses.push(address);
+    }
+    return addresses;
+}
+/**
+ * Get primary address for a worker based on preferences
+ */
+export function getPrimaryAddress(worker) {
+    const preferences = worker.preferences;
+    if (preferences?.primary) {
+        return resolveAddress(worker.contacts, preferences.primary);
+    }
+    // Default priority: slack > email > teams > sms > phone
+    const defaultPriority = ['slack', 'email', 'teams', 'sms', 'phone'];
+    for (const channel of defaultPriority) {
+        const address = resolveAddress(worker.contacts, channel);
+        if (address)
+            return address;
+    }
+    // Fall back to any available
+    const addresses = resolveWorkerAddresses(worker);
+    return addresses[0] || null;
+}
+/**
+ * Transport registry
+ */
+const transportRegistry = new Map();
+/**
+ * Register a transport handler
+ */
+export function registerTransport(transport, handler) {
+    transportRegistry.set(transport, handler);
+}
+/**
+ * Get transport handler
+ */
+export function getTransportHandler(transport) {
+    return transportRegistry.get(transport);
+}
+/**
+ * Check if transport is registered
+ */
+export function hasTransport(transport) {
+    return transportRegistry.has(transport);
+}
+/**
+ * List registered transports
+ */
+export function listTransports() {
+    return Array.from(transportRegistry.keys());
+}
+// =============================================================================
+// Default Transport Handlers (Stubs - implemented by providers)
+// =============================================================================
+/**
+ * Send via transport
+ */
+export async function sendViaTransport(transport, payload, config) {
+    const handler = transportRegistry.get(transport);
+    if (!handler) {
+        return {
+            success: false,
+            transport,
+            error: `Transport '${transport}' not registered`,
+        };
+    }
+    try {
+        return await handler(payload, config || { transport });
+    }
+    catch (error) {
+        return {
+            success: false,
+            transport,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Send to multiple transports (fan-out)
+ */
+export async function sendToMultipleTransports(transports, payload, configs) {
+    const results = await Promise.all(transports.map(transport => sendViaTransport(transport, payload, configs?.[transport])));
+    return results;
+}
+// =============================================================================
+// Worker Action to Transport
+// =============================================================================
+/**
+ * Build message payload from notify action
+ */
+export function buildNotifyPayload(action) {
+    return {
+        to: resolveActionTarget(action.object),
+        body: action.message,
+        type: 'notification',
+        priority: action.priority || 'normal',
+        metadata: action.metadata,
+    };
+}
+/**
+ * Build message payload from ask action
+ */
+export function buildAskPayload(action) {
+    return {
+        to: resolveActionTarget(action.object),
+        body: action.question,
+        type: 'question',
+        schema: action.schema,
+        timeout: action.timeout,
+        metadata: action.metadata,
+    };
+}
+/**
+ * Build message payload from approve action
+ */
+export function buildApprovePayload(action) {
+    return {
+        to: resolveActionTarget(action.object),
+        body: action.request,
+        type: 'approval',
+        timeout: action.timeout,
+        actions: [
+            { id: 'approve', label: 'Approve', style: 'primary', value: true },
+            { id: 'reject', label: 'Reject', style: 'danger', value: false },
+        ],
+        metadata: {
+            ...action.metadata,
+            context: action.context,
+        },
+    };
+}
+/**
+ * Resolve action target to address string
+ */
+function resolveActionTarget(target) {
+    if (typeof target === 'string')
+        return target;
+    if ('contacts' in target) {
+        const address = getPrimaryAddress(target);
+        return address?.value || target.id;
+    }
+    return target.id;
+}
+// =============================================================================
+// Integration with digital-tools Message/Call types
+// =============================================================================
+/**
+ * Message type mapping (from digital-tools)
+ */
+export const MessageTypeMapping = {
+    email: 'email',
+    sms: 'text',
+    slack: 'chat',
+    teams: 'chat',
+    discord: 'chat',
+    whatsapp: 'text',
+    telegram: 'text',
+    voice: 'voicemail', // For voicemail messages
+};
+/**
+ * Call type mapping (from digital-tools)
+ */
+export const CallTypeMapping = {
+    phone: 'phone',
+    voice: 'phone',
+    web: 'web',
+    video: 'video',
+};
+/**
+ * Convert worker notification to digital-tools Message format
+ */
+export function toDigitalToolsMessage(payload, transport) {
+    const messageType = MessageTypeMapping[transport] || 'chat';
+    return {
+        type: messageType,
+        to: Array.isArray(payload.to) ? payload.to : [payload.to],
+        from: payload.from,
+        subject: payload.subject,
+        body: payload.body,
+        html: payload.html,
+        metadata: {
+            ...payload.metadata,
+            workerActionType: payload.type,
+            priority: payload.priority,
+        },
+    };
+}
+/**
+ * Convert digital-tools Message to worker notification format
+ */
+export function fromDigitalToolsMessage(message) {
+    return {
+        to: message.to,
+        from: message.from,
+        subject: message.subject,
+        body: message.body,
+        html: message.html,
+        metadata: message.metadata,
+    };
+}

package/src/types.js

@@ -0,0 +1,71 @@
+/**
+ * Type definitions for digital-workers
+ *
+ * Digital workers (Agents and Humans) communicate through Actions that integrate
+ * with the ai-workflows system. Worker actions (notify, ask, approve, decide)
+ * are durable workflow actions with Actor/Object semantics.
+ *
+ * ## Key Concepts
+ *
+ * - **Worker**: Common interface for Agent and Human
+ * - **Contacts**: How a worker can be reached (email, slack, phone, etc.)
+ * - **Action**: Durable workflow action (notify, ask, approve, decide)
+ * - **Team**: Group of workers with shared contacts
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Worker Verbs - Following ai-database Verb pattern
+// ============================================================================
+/**
+ * Worker verbs following the ai-database conjugation pattern
+ *
+ * Each verb has:
+ * - action: Base form (notify, ask, approve, decide)
+ * - actor: Who does it (notifier, asker, approver, decider)
+ * - activity: Gerund (notifying, asking, approving, deciding)
+ * - reverse: Past forms (notifiedAt, notifiedBy, askedAt, etc.)
+ */
+export const WorkerVerbs = {
+    notify: {
+        action: 'notify',
+        actor: 'notifier',
+        act: 'notifies',
+        activity: 'notifying',
+        result: 'notification',
+        reverse: { at: 'notifiedAt', by: 'notifiedBy', via: 'notifiedVia' },
+    },
+    ask: {
+        action: 'ask',
+        actor: 'asker',
+        act: 'asks',
+        activity: 'asking',
+        result: 'question',
+        reverse: { at: 'askedAt', by: 'askedBy', via: 'askedVia' },
+    },
+    approve: {
+        action: 'approve',
+        actor: 'approver',
+        act: 'approves',
+        activity: 'approving',
+        result: 'approval',
+        reverse: { at: 'approvedAt', by: 'approvedBy', via: 'approvedVia' },
+        inverse: 'reject',
+    },
+    decide: {
+        action: 'decide',
+        actor: 'decider',
+        act: 'decides',
+        activity: 'deciding',
+        result: 'decision',
+        reverse: { at: 'decidedAt', by: 'decidedBy' },
+    },
+    do: {
+        action: 'do',
+        actor: 'doer',
+        act: 'does',
+        activity: 'doing',
+        result: 'task',
+        reverse: { at: 'doneAt', by: 'doneBy' },
+    },
+};