Runs

interface ExecutionRun {
  id: string;
  planId: string;
  planVersion: number;
  contactId: string;
  status: RunStatus;
  currentStep: string | null;
  stepsCompleted: number;
  stepsRemaining: number;
  startTick: number;
  currentTick: number;
  startedAt: Date;
  completedAt: Date | null;
  outcome: string | null;
  variables: Record<string, unknown>;
}

type RunStatus =
  | 'pending'
  | 'active'
  | 'waiting'
  | 'paused'
  | 'completed'
  | 'failed'
  | 'cancelled';

const runs = await engine.listRuns(filters?: {
  status?: RunStatus | RunStatus[];
  planId?: string;
  contactId?: string;
  startedAfter?: Date;
  startedBefore?: Date;
  limit?: number;
  offset?: number;
}): Promise<{ runs: ExecutionRun[]; total: number }>;

// All active runs
const active = await engine.listRuns({ status: 'active' });

// Runs for a specific contact
const contactRuns = await engine.listRuns({ contactId: 'contact_123' });

// Failed runs in the last 24 hours
const failed = await engine.listRuns({
  status: 'failed',
  startedAfter: new Date(Date.now() - 86400000),
});

const run = await engine.execute(plan, {
  contact: { id: 'contact_123', email: 'jane@example.com' },
});
// run.status === 'active'

await engine.pauseRun(run.id);
// run.status === 'paused'

await engine.resumeRun(run.id);
// run.status === 'active'

await engine.cancelRun(run.id, 'Contact requested removal');
// run.status === 'cancelled'
// Recorded in audit log with reason

// After final step executes:
// run.status === 'completed'
// run.outcome === 'replied' (from the end step definition)

const results = await engine.bulkExecute(plan, {
  contacts: Contact[],
  variables?: Record<string, unknown>,  // shared variables
  batchSize?: number,                   // default: 100
});

// results: { created: 950, skipped: 50, errors: 0 }
// Skipped = already enrolled or suppressed

await engine.bulkCancel(
  { planId: 'old-plan', status: 'active' },
  'Plan deprecated'
);