@auxiora/workflows 1.0.0

package/src/engine.ts

@@ -0,0 +1,296 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { getLogger } from '@auxiora/logger';
+import { audit } from '@auxiora/audit';
+import { getAuxioraDir } from '@auxiora/core';
+import type {
+  HumanWorkflow,
+  WorkflowStep,
+  WorkflowStatus,
+  WorkflowEvent,
+  ReminderConfig,
+  EscalationPolicy,
+  AutonomousAction,
+} from './types.js';
+
+const logger = getLogger('workflows:engine');
+
+export interface CreateWorkflowOptions {
+  name: string;
+  description: string;
+  createdBy: string;
+  steps: Array<{
+    name: string;
+    description: string;
+    assigneeId: string;
+    dependsOn?: string[];
+    action?: AutonomousAction;
+  }>;
+  reminder?: Partial<ReminderConfig>;
+  escalation?: Partial<EscalationPolicy>;
+  autonomous?: boolean;
+}
+
+const DEFAULT_REMINDER: ReminderConfig = {
+  enabled: false,
+  intervalMs: 3600_000, // 1 hour
+  maxReminders: 3,
+};
+
+const DEFAULT_ESCALATION: EscalationPolicy = {
+  enabled: false,
+  escalateAfterMs: 86400_000, // 24 hours
+  escalateToUserId: '',
+  maxEscalations: 1,
+};
+
+export class WorkflowEngine {
+  private filePath: string;
+
+  constructor(options?: { dir?: string }) {
+    const dir = options?.dir ?? path.join(getAuxioraDir(), 'workflows');
+    this.filePath = path.join(dir, 'workflows.json');
+  }
+
+  async createWorkflow(options: CreateWorkflowOptions): Promise<HumanWorkflow> {
+    const workflows = await this.readFile();
+    const now = Date.now();
+    const workflowId = `wf-${crypto.randomUUID().slice(0, 8)}`;
+
+    const steps: WorkflowStep[] = options.steps.map((s, i) => ({
+      id: `step-${i + 1}`,
+      name: s.name,
+      description: s.description,
+      assigneeId: s.assigneeId,
+      status: 'pending',
+      dependsOn: s.dependsOn ?? [],
+      ...(s.action ? { action: s.action } : {}),
+    }));
+
+    const workflow: HumanWorkflow = {
+      id: workflowId,
+      name: options.name,
+      description: options.description,
+      createdBy: options.createdBy,
+      status: 'pending',
+      steps,
+      reminder: { ...DEFAULT_REMINDER, ...options.reminder },
+      escalation: { ...DEFAULT_ESCALATION, ...options.escalation },
+      events: [],
+      createdAt: now,
+      updatedAt: now,
+      ...(options.autonomous ? { autonomous: true } : {}),
+    };
+
+    workflow.events.push(this.createEvent(workflowId, 'created', { userId: options.createdBy }));
+
+    workflows.push(workflow);
+    await this.writeFile(workflows);
+    void audit('workflow.created', { id: workflowId, name: options.name });
+    logger.debug('Created workflow', { id: workflowId });
+    return workflow;
+  }
+
+  async startWorkflow(workflowId: string): Promise<HumanWorkflow | undefined> {
+    const workflows = await this.readFile();
+    const workflow = workflows.find(w => w.id === workflowId);
+    if (!workflow || workflow.status !== 'pending') return undefined;
+
+    workflow.status = 'active';
+    workflow.updatedAt = Date.now();
+
+    // Activate steps with no dependencies
+    for (const step of workflow.steps) {
+      if (step.dependsOn.length === 0) {
+        step.status = 'active';
+      }
+    }
+
+    await this.writeFile(workflows);
+    void audit('workflow.started', { id: workflowId });
+    return workflow;
+  }
+
+  async completeStep(
+    workflowId: string,
+    stepId: string,
+    completedBy: string,
+    result?: string,
+  ): Promise<HumanWorkflow | undefined> {
+    const workflows = await this.readFile();
+    const workflow = workflows.find(w => w.id === workflowId);
+    if (!workflow || workflow.status !== 'active') return undefined;
+
+    const step = workflow.steps.find(s => s.id === stepId);
+    if (!step || step.status !== 'active') return undefined;
+
+    step.status = 'completed';
+    step.completedAt = Date.now();
+    step.completedBy = completedBy;
+    step.result = result;
+
+    workflow.events.push(
+      this.createEvent(workflowId, 'step_completed', {
+        stepId,
+        userId: completedBy,
+        details: result,
+      }),
+    );
+
+    // Advance: activate any steps whose dependencies are now met
+    this.advanceWorkflow(workflow);
+
+    workflow.updatedAt = Date.now();
+    await this.writeFile(workflows);
+    void audit('workflow.step_completed', { workflowId, stepId, completedBy });
+    return workflow;
+  }
+
+  async failStep(
+    workflowId: string,
+    stepId: string,
+    reason: string,
+  ): Promise<HumanWorkflow | undefined> {
+    const workflows = await this.readFile();
+    const workflow = workflows.find(w => w.id === workflowId);
+    if (!workflow || workflow.status !== 'active') return undefined;
+
+    const step = workflow.steps.find(s => s.id === stepId);
+    if (!step || step.status !== 'active') return undefined;
+
+    step.status = 'failed';
+    workflow.events.push(
+      this.createEvent(workflowId, 'step_failed', { stepId, details: reason }),
+    );
+
+    // Check if workflow should fail
+    const hasActiveSteps = workflow.steps.some(s => s.status === 'active' || s.status === 'pending');
+    if (!hasActiveSteps) {
+      workflow.status = 'failed';
+    }
+
+    workflow.updatedAt = Date.now();
+    await this.writeFile(workflows);
+    return workflow;
+  }
+
+  async cancelWorkflow(workflowId: string): Promise<boolean> {
+    const workflows = await this.readFile();
+    const workflow = workflows.find(w => w.id === workflowId);
+    if (!workflow || workflow.status === 'completed' || workflow.status === 'cancelled') return false;
+
+    workflow.status = 'cancelled';
+    workflow.updatedAt = Date.now();
+    workflow.events.push(this.createEvent(workflowId, 'cancelled'));
+
+    await this.writeFile(workflows);
+    void audit('workflow.cancelled', { id: workflowId });
+    return true;
+  }
+
+  async getWorkflow(workflowId: string): Promise<HumanWorkflow | undefined> {
+    const workflows = await this.readFile();
+    return workflows.find(w => w.id === workflowId);
+  }
+
+  async getStatus(workflowId: string): Promise<{ workflow: HumanWorkflow; progress: number } | undefined> {
+    const workflow = await this.getWorkflow(workflowId);
+    if (!workflow) return undefined;
+
+    const completed = workflow.steps.filter(s => s.status === 'completed').length;
+    const progress = workflow.steps.length > 0 ? completed / workflow.steps.length : 0;
+
+    return { workflow, progress };
+  }
+
+  async listActive(): Promise<HumanWorkflow[]> {
+    const workflows = await this.readFile();
+    return workflows.filter(w => w.status === 'active' || w.status === 'pending');
+  }
+
+  async listAll(): Promise<HumanWorkflow[]> {
+    return this.readFile();
+  }
+
+  async addEvent(
+    workflowId: string,
+    type: WorkflowEvent['type'],
+    extra?: { stepId?: string; userId?: string; details?: string },
+  ): Promise<boolean> {
+    const workflows = await this.readFile();
+    const workflow = workflows.find(w => w.id === workflowId);
+    if (!workflow) return false;
+
+    workflow.events.push(this.createEvent(workflowId, type, extra));
+    workflow.updatedAt = Date.now();
+    await this.writeFile(workflows);
+    return true;
+  }
+
+  async listByUser(userId: string): Promise<HumanWorkflow[]> {
+    const workflows = await this.readFile();
+    return workflows.filter(
+      w => w.createdBy === userId || w.steps.some(s => s.assigneeId === userId),
+    );
+  }
+
+  private advanceWorkflow(workflow: HumanWorkflow): void {
+    const completedIds = new Set(
+      workflow.steps.filter(s => s.status === 'completed').map(s => s.id),
+    );
+
+    for (const step of workflow.steps) {
+      if (step.status !== 'pending') continue;
+
+      const depsComplete = step.dependsOn.every(dep => completedIds.has(dep));
+      if (depsComplete) {
+        step.status = 'active';
+      }
+    }
+
+    // Check if all steps are completed
+    const allDone = workflow.steps.every(
+      s => s.status === 'completed' || s.status === 'skipped',
+    );
+    if (allDone) {
+      workflow.status = 'completed';
+      workflow.completedAt = Date.now();
+      workflow.events.push(this.createEvent(workflow.id, 'completed'));
+    }
+  }
+
+  private createEvent(
+    workflowId: string,
+    type: WorkflowEvent['type'],
+    extra?: { stepId?: string; userId?: string; details?: string },
+  ): WorkflowEvent {
+    return {
+      id: `evt-${crypto.randomUUID().slice(0, 8)}`,
+      workflowId,
+      type,
+      stepId: extra?.stepId,
+      userId: extra?.userId,
+      details: extra?.details,
+      timestamp: Date.now(),
+    };
+  }
+
+  private async readFile(): Promise<HumanWorkflow[]> {
+    try {
+      const content = await fs.readFile(this.filePath, 'utf-8');
+      return JSON.parse(content) as HumanWorkflow[];
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  private async writeFile(workflows: HumanWorkflow[]): Promise<void> {
+    const dir = path.dirname(this.filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(this.filePath, JSON.stringify(workflows, null, 2), 'utf-8');
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export type {
+  HumanWorkflow,
+  WorkflowStep,
+  WorkflowStatus,
+  StepStatus,
+  ReminderConfig,
+  EscalationPolicy,
+  WorkflowEvent,
+  AutonomousAction,
+} from './types.js';
+export { WorkflowEngine } from './engine.js';
+export type { CreateWorkflowOptions } from './engine.js';
+export { ReminderService } from './reminder.js';
+export type { ReminderTarget, ReminderSender } from './reminder.js';
+export { ApprovalManager } from './approval.js';
+export type { ApprovalRequest, ApprovalStatus } from './approval.js';
+export {
+  AutonomousExecutor,
+  type AutonomousExecutorDeps,
+  type TickResult,
+  type ToolResult as AutonomousToolResult,
+  type GateCheckResult,
+} from './autonomous-executor.js';

package/src/reminder.ts

@@ -0,0 +1,129 @@
+import { getLogger } from '@auxiora/logger';
+import type { HumanWorkflow, ReminderConfig } from './types.js';
+
+const logger = getLogger('workflows:reminder');
+
+export interface ReminderTarget {
+  userId: string;
+  workflowId: string;
+  stepId: string;
+  stepName: string;
+  workflowName: string;
+}
+
+export interface ReminderSender {
+  sendReminder(target: ReminderTarget, channelType?: string): Promise<void>;
+}
+
+interface ScheduledReminder {
+  workflowId: string;
+  stepId: string;
+  timer: ReturnType<typeof setInterval>;
+  count: number;
+  maxReminders: number;
+}
+
+export class ReminderService {
+  private reminders = new Map<string, ScheduledReminder>();
+  private sender?: ReminderSender;
+
+  setSender(sender: ReminderSender): void {
+    this.sender = sender;
+  }
+
+  scheduleReminder(
+    workflow: HumanWorkflow,
+    stepId: string,
+    config?: Partial<ReminderConfig>,
+  ): void {
+    const key = `${workflow.id}:${stepId}`;
+    if (this.reminders.has(key)) return;
+
+    const step = workflow.steps.find(s => s.id === stepId);
+    if (!step) return;
+
+    const intervalMs = config?.intervalMs ?? workflow.reminder.intervalMs;
+    const maxReminders = config?.maxReminders ?? workflow.reminder.maxReminders;
+
+    const scheduled: ScheduledReminder = {
+      workflowId: workflow.id,
+      stepId,
+      count: 0,
+      maxReminders,
+      timer: setInterval(() => {
+        void this.sendReminder(workflow, stepId, scheduled);
+      }, intervalMs),
+    };
+
+    this.reminders.set(key, scheduled);
+    logger.debug('Scheduled reminder', { workflowId: workflow.id, stepId, intervalMs });
+  }
+
+  cancelReminder(workflowId: string, stepId: string): void {
+    const key = `${workflowId}:${stepId}`;
+    const reminder = this.reminders.get(key);
+    if (reminder) {
+      clearInterval(reminder.timer);
+      this.reminders.delete(key);
+      logger.debug('Cancelled reminder', { workflowId, stepId });
+    }
+  }
+
+  cancelAllForWorkflow(workflowId: string): void {
+    for (const [key, reminder] of this.reminders) {
+      if (reminder.workflowId === workflowId) {
+        clearInterval(reminder.timer);
+        this.reminders.delete(key);
+      }
+    }
+  }
+
+  shutdown(): void {
+    for (const [, reminder] of this.reminders) {
+      clearInterval(reminder.timer);
+    }
+    this.reminders.clear();
+  }
+
+  getActiveCount(): number {
+    return this.reminders.size;
+  }
+
+  private async sendReminder(
+    workflow: HumanWorkflow,
+    stepId: string,
+    scheduled: ScheduledReminder,
+  ): Promise<void> {
+    scheduled.count++;
+
+    if (scheduled.count > scheduled.maxReminders) {
+      this.cancelReminder(workflow.id, stepId);
+      return;
+    }
+
+    const step = workflow.steps.find(s => s.id === stepId);
+    if (!step || step.status !== 'active') {
+      this.cancelReminder(workflow.id, stepId);
+      return;
+    }
+
+    if (this.sender) {
+      try {
+        await this.sender.sendReminder({
+          userId: step.assigneeId,
+          workflowId: workflow.id,
+          stepId,
+          stepName: step.name,
+          workflowName: workflow.name,
+        });
+        logger.debug('Sent reminder', {
+          workflowId: workflow.id,
+          stepId,
+          count: scheduled.count,
+        });
+      } catch (error) {
+        logger.debug('Failed to send reminder', { error: error as Error });
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+export type WorkflowStatus = 'pending' | 'active' | 'completed' | 'failed' | 'cancelled';
+export type StepStatus = 'pending' | 'active' | 'completed' | 'failed' | 'skipped';
+
+/** An action that can be auto-executed by the AutonomousExecutor. */
+export interface AutonomousAction {
+  /** Tool name to execute (e.g. 'file_read', 'bash', 'email_compose'). */
+  tool: string;
+  /** Parameters to pass to the tool. */
+  params: Record<string, unknown>;
+  /** Trust domain for gate checking (e.g. 'files', 'shell', 'email'). */
+  trustDomain: string;
+  /** Minimum trust level required (0-4). */
+  trustRequired: number;
+  /** Optional tool to call for rollback on failure. */
+  rollbackTool?: string;
+  /** Optional params for the rollback tool. */
+  rollbackParams?: Record<string, unknown>;
+}
+
+export interface WorkflowStep {
+  id: string;
+  name: string;
+  description: string;
+  assigneeId: string;
+  status: StepStatus;
+  dependsOn: string[];
+  completedAt?: number;
+  completedBy?: string;
+  result?: string;
+  /** If present, step can be auto-executed by AutonomousExecutor. */
+  action?: AutonomousAction;
+}
+
+export interface ReminderConfig {
+  enabled: boolean;
+  intervalMs: number;
+  maxReminders: number;
+  channelType?: string;
+}
+
+export interface EscalationPolicy {
+  enabled: boolean;
+  escalateAfterMs: number;
+  escalateToUserId: string;
+  maxEscalations: number;
+}
+
+export interface WorkflowEvent {
+  id: string;
+  workflowId: string;
+  type: 'created' | 'step_completed' | 'step_failed' | 'step_trust_denied' | 'step_rolled_back' | 'reminder_sent' | 'escalated' | 'completed' | 'cancelled' | 'approval_requested' | 'approved' | 'rejected';
+  stepId?: string;
+  userId?: string;
+  details?: string;
+  timestamp: number;
+}
+
+export interface HumanWorkflow {
+  id: string;
+  name: string;
+  description: string;
+  createdBy: string;
+  status: WorkflowStatus;
+  steps: WorkflowStep[];
+  reminder: ReminderConfig;
+  escalation: EscalationPolicy;
+  events: WorkflowEvent[];
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  /** If true, steps with actions are auto-executed by AutonomousExecutor. */
+  autonomous?: boolean;
+}