digital-workers 2.1.1 → 2.3.0

package/src/goals.js

@@ -1,205 +0,0 @@
-/**
- * Goals definition for digital workers
- */
-/**
- * Define worker goals
- *
- * Goals provide direction and metrics for workers and teams.
- * Supports short-term, long-term, and strategic objectives with KPIs.
- *
- * @param definition - Goals definition
- * @returns The defined goals
- *
- * @example
- * ```ts
- * const engineeringGoals = Goals({
- *   shortTerm: [
- *     'Complete Q1 roadmap features',
- *     'Reduce bug backlog by 30%',
- *     'Improve test coverage to 80%',
- *   ],
- *   longTerm: [
- *     'Migrate to microservices architecture',
- *     'Achieve 99.9% uptime',
- *     'Build scalable platform for 1M users',
- *   ],
- *   strategic: [
- *     'Become industry leader in performance',
- *     'Enable product innovation through technology',
- *   ],
- *   metrics: [
- *     {
- *       name: 'Deployment Frequency',
- *       description: 'Number of deployments per week',
- *       current: 5,
- *       target: 10,
- *       unit: 'deploys/week',
- *       trend: 'up',
- *       period: 'weekly',
- *     },
- *     {
- *       name: 'Mean Time to Recovery',
- *       description: 'Average time to recover from incidents',
- *       current: 45,
- *       target: 30,
- *       unit: 'minutes',
- *       trend: 'down',
- *       period: 'monthly',
- *     },
- *   ],
- * })
- * ```
- *
- * @example
- * ```ts
- * const supportGoals = Goals({
- *   shortTerm: [
- *     'Achieve 95% customer satisfaction',
- *     'Reduce average response time to < 5 min',
- *   ],
- *   longTerm: [
- *     'Build comprehensive knowledge base',
- *     'Implement AI-first support workflow',
- *   ],
- *   metrics: [
- *     {
- *       name: 'Customer Satisfaction',
- *       description: 'CSAT score from surveys',
- *       current: 92,
- *       target: 95,
- *       unit: '%',
- *       trend: 'up',
- *       period: 'monthly',
- *     },
- *   ],
- * })
- * ```
- */
-export function Goals(definition) {
-    return definition;
-}
-/**
- * Add a short-term goal
- *
- * @param goals - The goals object
- * @param goal - Goal to add
- * @returns Updated goals
- *
- * @example
- * ```ts
- * const updated = Goals.addShortTerm(engineeringGoals, 'Complete security audit')
- * ```
- */
-Goals.addShortTerm = (goals, goal) => ({
-    ...goals,
-    shortTerm: [...goals.shortTerm, goal],
-});
-/**
- * Add a long-term goal
- *
- * @param goals - The goals object
- * @param goal - Goal to add
- * @returns Updated goals
- *
- * @example
- * ```ts
- * const updated = Goals.addLongTerm(engineeringGoals, 'Build ML platform')
- * ```
- */
-Goals.addLongTerm = (goals, goal) => ({
-    ...goals,
-    longTerm: [...goals.longTerm, goal],
-});
-/**
- * Add a strategic goal
- *
- * @param goals - The goals object
- * @param goal - Goal to add
- * @returns Updated goals
- *
- * @example
- * ```ts
- * const updated = Goals.addStrategic(engineeringGoals, 'Become carbon neutral')
- * ```
- */
-Goals.addStrategic = (goals, goal) => ({
-    ...goals,
-    strategic: [...(goals.strategic || []), goal],
-});
-/**
- * Add a KPI metric
- *
- * @param goals - The goals object
- * @param kpi - KPI to add
- * @returns Updated goals
- *
- * @example
- * ```ts
- * const updated = Goals.addMetric(engineeringGoals, {
- *   name: 'Code Quality',
- *   description: 'Code quality score from SonarQube',
- *   current: 85,
- *   target: 90,
- *   unit: 'score',
- *   trend: 'up',
- *   period: 'weekly',
- * })
- * ```
- */
-Goals.addMetric = (goals, kpi) => ({
-    ...goals,
-    metrics: [...(goals.metrics || []), kpi],
-});
-/**
- * Update a KPI metric
- *
- * @param goals - The goals object
- * @param name - Name of KPI to update
- * @param updates - Fields to update
- * @returns Updated goals
- *
- * @example
- * ```ts
- * const updated = Goals.updateMetric(engineeringGoals, 'Deployment Frequency', {
- *   current: 8,
- *   trend: 'up',
- * })
- * ```
- */
-Goals.updateMetric = (goals, name, updates) => ({
-    ...goals,
-    metrics: goals.metrics?.map((kpi) => kpi.name === name ? { ...kpi, ...updates } : kpi),
-});
-/**
- * Get progress for a KPI (0-1)
- *
- * @param kpi - The KPI
- * @returns Progress value between 0 and 1
- *
- * @example
- * ```ts
- * const kpi = { current: 75, target: 100 }
- * const progress = Goals.progress(kpi) // 0.75
- * ```
- */
-Goals.progress = (kpi) => {
-    if (kpi.target === 0)
-        return 0;
-    return Math.min(1, Math.max(0, kpi.current / kpi.target));
-};
-/**
- * Check if a KPI is on track
- *
- * @param kpi - The KPI
- * @param threshold - Minimum progress to be considered "on track" (default: 0.8)
- * @returns Whether the KPI is on track
- *
- * @example
- * ```ts
- * const kpi = { current: 85, target: 100 }
- * const onTrack = Goals.onTrack(kpi) // true (85% >= 80% threshold)
- * ```
- */
-Goals.onTrack = (kpi, threshold = 0.8) => {
-    return Goals.progress(kpi) >= threshold;
-};

package/src/index.js

@@ -1,68 +0,0 @@
-/**
- * digital-workers - Abstract interface for organizing digital work
- *
- * This package provides the foundational abstraction for structuring work
- * independent of whether AI agents or humans perform individual tasks. It
- * defines a unified Worker interface that enables workflows to be designed
- * once and executed by any combination of AI and human workers.
- *
- * Package relationships:
- * - `autonomous-agents` - Implements Worker for AI agents
- * - `human-in-the-loop` - Implements Worker for humans
- * - `ai-workflows` - Uses digital-workers to orchestrate execution
- *
- * The key insight: define WHAT work needs to happen, not WHO does it.
- *
- * ## Worker Actions
- *
- * 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)
- *
- * @example
- * ```ts
- * import { Workflow } from 'ai-workflows'
- * import { registerWorkerActions, withWorkers } from 'digital-workers'
- *
- * const workflow = Workflow($ => {
- *   registerWorkerActions($)
- *   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' }
- *     )
- *
- *     if (approval.approved) {
- *       await worker$.notify(expense.submitter, 'Expense approved!')
- *     }
- *   })
- * })
- * ```
- *
- * @packageDocumentation
- */
-// Export workflow integration
-export { registerWorkerActions, withWorkers, handleNotify, handleAsk, handleApprove, handleDecide, handleDo, notify as notifyAction, ask as askAction, approve as approveAction, decide as decideAction, } from './actions.js';
-// Export core functions
-export { Role } from './role.js';
-export { Team } from './team.js';
-export { Goals } from './goals.js';
-export { approve } from './approve.js';
-export { ask } from './ask.js';
-export { do } from './do.js';
-export { decide } from './decide.js';
-export { generate } from './generate.js';
-export { is } from './is.js';
-export { notify } from './notify.js';
-export { kpis, okrs } from './kpis.js';
-// Export verb definitions
-export { WorkerVerbs } from './types.js';
-export { channelToTransport, getWorkerTransports, getTeamTransports, resolveAddress, resolveWorkerAddresses, getPrimaryAddress, registerTransport, getTransportHandler, hasTransport, listTransports, sendViaTransport, sendToMultipleTransports, buildNotifyPayload, buildAskPayload, buildApprovePayload, toDigitalToolsMessage, fromDigitalToolsMessage, MessageTypeMapping, CallTypeMapping, } from './transports.js';

package/src/is.js

@@ -1,317 +0,0 @@
-/**
- * Type validation and checking functionality for digital workers
- */
-import { generateObject } from 'ai-functions';
-import { schema as convertSchema } from 'ai-functions';
-/**
- * Check if a value matches an expected type or schema
- *
- * Uses AI-powered validation for complex types and schemas.
- * Can also perform type coercion when enabled.
- *
- * @param value - The value to check
- * @param type - Type name or schema to validate against
- * @param options - Validation options
- * @returns Promise resolving to validation result
- *
- * @example
- * ```ts
- * // Simple type checking
- * const result = await is('hello@example.com', 'email')
- * console.log(result.valid) // true
- * ```
- *
- * @example
- * ```ts
- * // Schema validation
- * const result = await is(
- *   { name: 'John', age: 30 },
- *   {
- *     name: 'Full name',
- *     age: 'Age in years (number)',
- *     email: 'Email address',
- *   }
- * )
- * console.log(result.valid) // false - missing email
- * console.log(result.errors) // ['Missing required field: email']
- * ```
- *
- * @example
- * ```ts
- * // With coercion
- * const result = await is('123', 'number', { coerce: true })
- * console.log(result.valid) // true
- * console.log(result.value) // 123 (as number)
- * ```
- */
-export async function is(value, type, options = {}) {
-    const { coerce = false, strict = false } = options;
-    // Handle simple type strings
-    if (typeof type === 'string') {
-        return validateSimpleType(value, type, { coerce, strict });
-    }
-    // Handle schema validation
-    return validateSchema(value, type, { coerce, strict });
-}
-/**
- * Validate against a simple type name
- */
-async function validateSimpleType(value, type, options) {
-    const { coerce, strict } = options;
-    // Built-in JavaScript types
-    const builtInTypes = {
-        string: (v) => typeof v === 'string',
-        number: (v) => typeof v === 'number' && !isNaN(v),
-        boolean: (v) => typeof v === 'boolean',
-        object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v),
-        array: (v) => Array.isArray(v),
-        null: (v) => v === null,
-        undefined: (v) => v === undefined,
-        function: (v) => typeof v === 'function',
-    };
-    // Check built-in types first
-    if (type in builtInTypes) {
-        const isValid = builtInTypes[type](value);
-        if (!isValid && coerce) {
-            // Try to coerce the value
-            const coerced = coerceValue(value, type);
-            if (coerced.success) {
-                return {
-                    valid: true,
-                    value: coerced.value,
-                };
-            }
-        }
-        return {
-            valid: isValid,
-            value: isValid ? value : undefined,
-            errors: isValid ? undefined : [`Value is not a valid ${type}`],
-        };
-    }
-    // Use AI for complex type validation
-    const result = await generateObject({
-        model: 'sonnet',
-        schema: {
-            valid: 'Whether the value matches the expected type (boolean)',
-            errors: ['List of validation errors if invalid'],
-            coercedValue: coerce ? 'The value coerced to the expected type' : undefined,
-        },
-        system: `You are a type validation expert. Determine if a value matches an expected type.
-
-${coerce ? 'If the value can be coerced to the expected type, provide the coerced value.' : ''}
-${strict ? 'Be strict in your validation - require exact type matches.' : 'Be flexible - allow reasonable type conversions.'}`,
-        prompt: `Validate if this value matches the expected type:
-
-Value: ${JSON.stringify(value)}
-Type: ${type}
-
-Determine if the value is valid for this type.`,
-    });
-    const validation = result.object;
-    return {
-        valid: validation.valid,
-        value: coerce && validation.coercedValue !== undefined ? validation.coercedValue : value,
-        errors: validation.valid ? undefined : validation.errors,
-    };
-}
-/**
- * Validate against a schema
- */
-async function validateSchema(value, schema, options) {
-    const { coerce, strict } = options;
-    try {
-        // Convert SimpleSchema to Zod schema
-        const zodSchema = convertSchema(schema);
-        // Parse the value
-        const parsed = zodSchema.parse(value);
-        return {
-            valid: true,
-            value: parsed,
-        };
-    }
-    catch (error) {
-        if (strict) {
-            return {
-                valid: false,
-                errors: [error.message],
-            };
-        }
-        // Use AI for more flexible validation
-        const result = await generateObject({
-            model: 'sonnet',
-            schema: {
-                valid: 'Whether the value matches the schema (boolean)',
-                errors: ['List of validation errors'],
-                coercedValue: coerce ? 'The value with corrections/coercions applied' : undefined,
-            },
-            system: `You are a schema validation expert. Validate a value against a schema.
-
-${coerce ? 'Try to coerce the value to match the schema where reasonable.' : ''}
-Be helpful - provide clear error messages.`,
-            prompt: `Validate this value against the schema:
-
-Value:
-${JSON.stringify(value, null, 2)}
-
-Schema:
-${JSON.stringify(schema, null, 2)}
-
-Check if the value matches the schema structure and types.`,
-        });
-        const validation = result.object;
-        return {
-            valid: validation.valid,
-            value: coerce && validation.coercedValue !== undefined ? validation.coercedValue : value,
-            errors: validation.valid ? undefined : validation.errors,
-        };
-    }
-}
-/**
- * Try to coerce a value to a specific type
- */
-function coerceValue(value, type) {
-    try {
-        switch (type) {
-            case 'string':
-                return { success: true, value: String(value) };
-            case 'number':
-                const num = Number(value);
-                return { success: !isNaN(num), value: num };
-            case 'boolean':
-                if (typeof value === 'string') {
-                    const lower = value.toLowerCase();
-                    if (lower === 'true' || lower === '1') {
-                        return { success: true, value: true };
-                    }
-                    if (lower === 'false' || lower === '0') {
-                        return { success: true, value: false };
-                    }
-                }
-                return { success: true, value: Boolean(value) };
-            case 'array':
-                if (Array.isArray(value)) {
-                    return { success: true, value };
-                }
-                return { success: true, value: [value] };
-            default:
-                return { success: false };
-        }
-    }
-    catch {
-        return { success: false };
-    }
-}
-/**
- * Check if a value is valid email
- *
- * @param value - Value to check
- * @returns Promise resolving to validation result
- *
- * @example
- * ```ts
- * const result = await is.email('test@example.com')
- * console.log(result.valid) // true
- * ```
- */
-is.email = async (value) => {
-    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-    const valid = typeof value === 'string' && emailRegex.test(value);
-    return {
-        valid,
-        value: valid ? value : undefined,
-        errors: valid ? undefined : ['Invalid email format'],
-    };
-};
-/**
- * Check if a value is a valid URL
- *
- * @param value - Value to check
- * @returns Promise resolving to validation result
- */
-is.url = async (value) => {
-    try {
-        if (typeof value !== 'string') {
-            return {
-                valid: false,
-                errors: ['Value must be a string'],
-            };
-        }
-        new URL(value);
-        return {
-            valid: true,
-            value,
-        };
-    }
-    catch {
-        return {
-            valid: false,
-            errors: ['Invalid URL format'],
-        };
-    }
-};
-/**
- * Check if a value is a valid date
- *
- * @param value - Value to check
- * @param options - Validation options
- * @returns Promise resolving to validation result
- */
-is.date = async (value, options = {}) => {
-    const { coerce } = options;
-    if (value instanceof Date) {
-        return {
-            valid: !isNaN(value.getTime()),
-            value,
-            errors: isNaN(value.getTime()) ? ['Invalid date'] : undefined,
-        };
-    }
-    if (coerce) {
-        try {
-            const date = new Date(value);
-            if (!isNaN(date.getTime())) {
-                return {
-                    valid: true,
-                    value: date,
-                };
-            }
-        }
-        catch {
-            // Fall through to invalid
-        }
-    }
-    return {
-        valid: false,
-        errors: ['Invalid date'],
-    };
-};
-/**
- * Check if a value matches a custom validation function
- *
- * @param value - Value to check
- * @param validator - Validation function
- * @returns Promise resolving to validation result
- *
- * @example
- * ```ts
- * const result = await is.custom(
- *   42,
- *   (v) => typeof v === 'number' && v > 0 && v < 100
- * )
- * ```
- */
-is.custom = async (value, validator) => {
-    try {
-        const valid = await validator(value);
-        return {
-            valid,
-            value: valid ? value : undefined,
-            errors: valid ? undefined : ['Custom validation failed'],
-        };
-    }
-    catch (error) {
-        return {
-            valid: false,
-            errors: [error.message],
-        };
-    }
-};